Skip to content

Latest commit

 

History

History
156 lines (126 loc) · 4.61 KB

AGENTS.md

File metadata and controls

156 lines (126 loc) · 4.61 KB

SOLAPI-PYTHON KNOWLEDGE BASE

Generated: 2026-01-21 Commit: b77fdd9 Branch: main

OVERVIEW

Python SDK for SOLAPI messaging platform. Sends SMS/LMS/MMS/Kakao/Naver/RCS messages in Korea. Thin wrapper around REST API using httpx + Pydantic v2.

STRUCTURE

solapi-python/
├── solapi/              # Main package (single export: SolapiMessageService)
│   ├── services/        # message_service.py - all API operations
│   ├── model/           # Pydantic models (see solapi/model/AGENTS.md)
│   ├── lib/             # authenticator.py, fetcher.py
│   └── error/           # MessageNotReceivedError only
├── tests/               # pytest integration tests
├── examples/            # Feature-based usage examples
└── debug/               # Dev test scripts (not part of package)

WHERE TO LOOK

Task Location Notes
Send messages solapi/services/message_service.py All 10 API methods in single class
Request models solapi/model/request/ Pydantic BaseModel with validators
Response models solapi/model/response/ Separate from request models
Kakao/Naver/RCS solapi/model/{kakao,naver,rcs}/ Domain-specific models
Authentication solapi/lib/authenticator.py HMAC-SHA256 signature
HTTP client solapi/lib/fetcher.py httpx with 3 retries
Test fixtures tests/conftest.py env-based credentials
Usage examples examples/simple/ Copy-paste ready

CONVENTIONS

Pydantic Everywhere

  • ALL models extend BaseModel
  • Field aliases: Field(alias="camelCase") for API compatibility
  • Validators: @field_validator for normalization (e.g., phone numbers)

Model Organization (Domain-Driven)

model/
├── request/       # Outbound API payloads
├── response/      # Inbound API responses
├── kakao/         # Kakao-specific (option, button)
├── naver/         # Naver-specific
├── rcs/           # RCS-specific
└── webhook/       # Delivery reports

Naming

  • Files: snake_case.py
  • Classes: PascalCase
  • Request suffix: *Request (e.g., SendMessageRequest)
  • Response suffix: *Response (e.g., SendMessageResponse)

Code Style (Ruff)

  • Line length: 88
  • Quote style: double
  • Import sorting: isort (I rule)
  • Target: Python 3.9+

Tidy First Principles

  • Never mix refactoring and feature changes in the same commit
  • Tidy related code before making behavioral changes
  • Tidying: guard clauses, dead code removal, rename, extract conditionals
  • Separate tidying commits from feature commits

ANTI-PATTERNS (THIS PROJECT)

NEVER

  • Add CLI/console scripts - this is library-only
  • Create multiple service classes - all goes in SolapiMessageService
  • Mix request/response models - they're deliberately separate
  • Use dataclasses or TypedDict for API models - Pydantic only
  • Hardcode credentials - use env vars

VERSION SYNC REQUIRED

# solapi/model/request/__init__.py
VERSION = "python/5.0.3"  # MUST update on every release!

Also update pyproject.toml version.

UNIQUE PATTERNS

Single Service Class

# All API methods in one class (318 lines)
class SolapiMessageService:
    def send(...)           # SMS/LMS/MMS/Kakao/Naver/RCS
    def upload_file(...)    # Storage
    def get_balance(...)    # Account
    def get_groups(...)     # Message groups
    def get_messages(...)   # Message history
    def cancel_scheduled_message(...)

Minimal Error Handling

  • Only MessageNotReceivedError exists
  • API errors raised as generic Exception with errorCode, errorMessage

Authentication Flow

SolapiMessageService.__init__(api_key, api_secret)
  → Authenticator.get_auth_info()
  → HMAC-SHA256 signature
  → Authorization header

COMMANDS

# Install
pip install solapi

# Dev setup
pip install -e ".[dev]"

# Lint & format
ruff check --fix .
ruff format .

# Test (requires env vars)
export SOLAPI_API_KEY="..."
export SOLAPI_API_SECRET="..."
export SOLAPI_SENDER="..."
export SOLAPI_RECIPIENT="..."
pytest

# Build
python -m build

ENV VARS (Testing)

Variable Purpose
SOLAPI_API_KEY API authentication
SOLAPI_API_SECRET API authentication
SOLAPI_SENDER Registered sender number
SOLAPI_RECIPIENT Test recipient number
SOLAPI_KAKAO_PF_ID Kakao business channel
SOLAPI_KAKAO_TEMPLATE_ID Kakao template

NOTES

  • No CI/CD pipeline - testing/linting is local only
  • uv workspace includes Django webhook example
  • Tests are integration tests (hit real API)
  • Korean comments in some files (i18n TODO exists)