Metadata-Version: 2.4
Name: stellavend-sdk
Version: 1.0.1
Summary: StellaVend Open API SDK for Python
License-Expression: MIT
Project-URL: Homepage, https://github.com/TeamStella/stellavend-sdk-python
Project-URL: Repository, https://github.com/TeamStella/stellavend-sdk-python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Framework :: AsyncIO
Classifier: Typing :: Typed
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: aiohttp>=3.8.0

# StellaVend Open API SDK for Python

StellaVend Open API를 사용하기 위한 Python SDK입니다.

> Discord 봇용 SDK는 `stellavend-bot-sdk`를 사용하세요.

## 설치

```bash
pip install stellavend-sdk
```

## 사용법

### 초기화

```python
from stellavend_api import StellaVendClient

client = StellaVendClient(
    api_base="https://stellavend.com/api/v1/mystore",
    api_key="sk-sv-..."  # Open API Key
)
```

### 상점 정보

```python
store = await client.get_store()
print(store.name)
```

### 상품 관리

```python
# 목록 조회
products = await client.get_products(limit=50)

# 상세 조회
product = await client.get_product("prod_xxx")

# 생성
new_product = await client.create_product(
    name="새 상품",
    price_krw=10000,
    description="상품 설명"
)

# 수정
await client.update_product("prod_xxx", price_krw=15000, is_active=True)

# 삭제
await client.delete_product("prod_xxx")
```

### 재고 관리

```python
# 재고 조회
stock = await client.get_stock("prod_xxx")
print(f"{stock.count}개 재고")

# 재고 추가
result = await client.add_stock("prod_xxx", ["item1", "item2", "item3"])
print(f"{result['added']}개 추가됨, 총 {result['total']}개")

# 재고 전체 삭제
await client.clear_stock("prod_xxx")
```

### 카테고리 관리

```python
categories = await client.get_categories()
await client.create_category(name="새 카테고리", color="#ff0000")
await client.update_category("cat_xxx", name="수정된 이름")
await client.delete_category("cat_xxx")
```

### 등급 관리

```python
grades = await client.get_grades()
await client.create_grade(
    name="VIP",
    min_spend_krw=100000,
    discount_type="percent",
    discount_value=10
)
```

### 쿠폰 관리

```python
coupons = await client.get_coupons()
await client.create_coupon(
    code="WELCOME10",
    type="percent",
    value=10,
    max_uses=100,
    expires_at="2024-12-31T23:59:59Z"
)
```

### 회원 관리

```python
# 목록 조회
users = await client.get_users(limit=100)

# 상세 조회
user = await client.get_user("user_xxx")

# 잔액 조정
await client.adjust_balance("user_xxx", 5000, "이벤트 지급")
await client.adjust_balance("user_xxx", -1000, "패널티 차감")

# 등급 설정
await client.set_grade("user_xxx", "grade_vip")
```

### 충전 요청 관리

```python
charges = await client.get_charges(status="pending")
await client.approve_charge("charge_xxx", approved_krw=10000)
await client.reject_charge("charge_xxx", reason="증빙 불충분")
```

### 주문 조회

```python
orders = await client.get_orders(status="completed", limit=50)
order = await client.get_order("order_xxx")
print(order.delivered_items)
```

### 후기 관리

```python
reviews = await client.get_reviews(product_id="prod_xxx")
await client.hide_review("review_xxx", True)
await client.delete_review("review_xxx")
```

### 분석 데이터

```python
analytics = await client.get_analytics("7d")
print(f"매출: {analytics.sales_krw}원, 주문: {analytics.order_count}건")
```

### 설정

```python
settings = await client.get_settings()
await client.update_settings(
    announcement="새 공지사항",
    bank_charge=True
)
```

### 웹훅

```python
webhooks = await client.get_webhooks()
await client.create_webhook(
    url="https://example.com/webhook",
    events=["order.completed", "charge.approved"]
)
```

### Context Manager 사용

```python
async with StellaVendClient(api_base, api_key) as client:
    products = await client.get_products()
    # 자동으로 세션 정리됨
```

### 에러 처리

```python
from stellavend_api import StellaVendClient, StellaVendError

try:
    await client.get_product("invalid_id")
except StellaVendError as e:
    print(f"API 오류 ({e.status}): {e}")
    print(f"에러 코드: {e.code}")
```

## 타입

모든 응답은 dataclass로 정의되어 있습니다:

- `Store`, `Product`, `Category`, `Grade`, `Coupon`
- `User`, `ChargeRequest`, `Order`, `Review`
- `Analytics`, `Settings`, `Webhook`

## 라이선스

MIT
