stellavend-api-sdk 1.0.0__py3-none-any.whl

stellavend_api/__init__.py

@@ -0,0 +1,47 @@
+"""
+StellaVend Open API SDK for Python
+
+Open API Key (sk-sv-...) 를 사용하는 일반 API SDK입니다.
+Discord 봇용 SDK는 stellavend-bot-sdk를 사용하세요.
+"""
+
+from .client import StellaVendClient, StellaVendError
+from .types import (
+    Store,
+    Product,
+    BulkTier,
+    Category,
+    Grade,
+    Coupon,
+    User,
+    ChargeRequest,
+    Order,
+    Review,
+    Analytics,
+    Settings,
+    Webhook,
+    StockResult,
+    BalanceResult,
+)
+
+__all__ = [
+    "StellaVendClient",
+    "StellaVendError",
+    "Store",
+    "Product",
+    "BulkTier",
+    "Category",
+    "Grade",
+    "Coupon",
+    "User",
+    "ChargeRequest",
+    "Order",
+    "Review",
+    "Analytics",
+    "Settings",
+    "Webhook",
+    "StockResult",
+    "BalanceResult",
+]
+
+__version__ = "1.0.0"

stellavend_api/client.py

@@ -0,0 +1,534 @@
+"""
+StellaVend Open API Client
+"""
+
+from typing import Optional, List, Dict, Any
+from urllib.parse import quote
+import aiohttp
+
+from .types import (
+    Store,
+    Product,
+    Category,
+    Grade,
+    Coupon,
+    User,
+    ChargeRequest,
+    Order,
+    Review,
+    Analytics,
+    Settings,
+    Webhook,
+    StockResult,
+    BalanceResult,
+)
+
+
+class StellaVendError(Exception):
+    """StellaVend API Error"""
+
+    def __init__(
+        self,
+        message: str,
+        status: int,
+        code: Optional[str] = None,
+        response: Optional[Dict[str, Any]] = None,
+    ):
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.response = response
+
+
+class StellaVendClient:
+    """
+    StellaVend Open API Client
+
+    Args:
+        api_base: API base URL (e.g., "https://stellavend.com/api/v1/mystore")
+        api_key: Open API Key (sk-sv-...)
+    """
+
+    def __init__(self, api_base: str, api_key: str):
+        self.api_base = api_base.rstrip("/")
+        self.api_key = api_key
+        self._session: Optional[aiohttp.ClientSession] = None
+
+    async def _get_session(self) -> aiohttp.ClientSession:
+        if self._session is None or self._session.closed:
+            self._session = aiohttp.ClientSession()
+        return self._session
+
+    async def close(self):
+        """Close the HTTP session"""
+        if self._session and not self._session.closed:
+            await self._session.close()
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        await self.close()
+
+    async def _request(
+        self,
+        method: str,
+        endpoint: str,
+        body: Optional[Dict[str, Any]] = None,
+        params: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        session = await self._get_session()
+        url = f"{self.api_base}{endpoint}"
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+        }
+
+        query_params = {}
+        if params:
+            for k, v in params.items():
+                if v is not None:
+                    query_params[k] = str(v)
+
+        async with session.request(
+            method, url, headers=headers, json=body, params=query_params or None
+        ) as response:
+            data = await response.json()
+
+            if not response.ok or data.get("ok") is False:
+                raise StellaVendError(
+                    data.get("error") or data.get("message") or f"API Error: {response.status}",
+                    response.status,
+                    data.get("code"),
+                    data,
+                )
+
+            return data
+
+    # ============ Store ============
+
+    async def get_store(self) -> Store:
+        """Get store information"""
+        data = await self._request("GET", "/")
+        return Store.from_dict(data.get("store", {}))
+
+    # ============ Products ============
+
+    async def get_products(
+        self, *, limit: Optional[int] = None, offset: Optional[int] = None
+    ) -> List[Product]:
+        """Get list of products"""
+        data = await self._request("GET", "/products", params={"limit": limit, "offset": offset})
+        return [Product.from_dict(p) for p in data.get("products", [])]
+
+    async def get_product(self, product_id: str) -> Product:
+        """Get product details"""
+        data = await self._request("GET", f"/products/{quote(product_id)}")
+        return Product.from_dict(data.get("product", {}))
+
+    async def create_product(
+        self,
+        *,
+        name: str,
+        price_krw: int,
+        description: Optional[str] = None,
+        detail_text: Optional[str] = None,
+        category_id: Optional[str] = None,
+        is_active: Optional[bool] = None,
+    ) -> Product:
+        """Create a new product"""
+        body: Dict[str, Any] = {"name": name, "priceKrw": price_krw}
+        if description is not None:
+            body["description"] = description
+        if detail_text is not None:
+            body["detailText"] = detail_text
+        if category_id is not None:
+            body["categoryId"] = category_id
+        if is_active is not None:
+            body["isActive"] = is_active
+
+        data = await self._request("POST", "/products", body)
+        return Product.from_dict(data.get("product", {}))
+
+    async def update_product(
+        self,
+        product_id: str,
+        *,
+        name: Optional[str] = None,
+        price_krw: Optional[int] = None,
+        description: Optional[str] = None,
+        detail_text: Optional[str] = None,
+        category_id: Optional[str] = None,
+        is_active: Optional[bool] = None,
+    ) -> Product:
+        """Update a product"""
+        body: Dict[str, Any] = {}
+        if name is not None:
+            body["name"] = name
+        if price_krw is not None:
+            body["priceKrw"] = price_krw
+        if description is not None:
+            body["description"] = description
+        if detail_text is not None:
+            body["detailText"] = detail_text
+        if category_id is not None:
+            body["categoryId"] = category_id
+        if is_active is not None:
+            body["isActive"] = is_active
+
+        data = await self._request("PATCH", f"/products/{quote(product_id)}", body)
+        return Product.from_dict(data.get("product", {}))
+
+    async def delete_product(self, product_id: str) -> bool:
+        """Delete a product"""
+        await self._request("DELETE", f"/products/{quote(product_id)}")
+        return True
+
+    # ============ Stock ============
+
+    async def get_stock(self, product_id: str) -> StockResult:
+        """Get product stock"""
+        data = await self._request("GET", f"/products/{quote(product_id)}/stock")
+        return StockResult(lines=data.get("lines", []), count=data.get("count", 0))
+
+    async def add_stock(self, product_id: str, lines: List[str]) -> Dict[str, int]:
+        """Add stock to a product"""
+        data = await self._request("POST", f"/products/{quote(product_id)}/stock", {"lines": lines})
+        return {"added": data.get("added", 0), "total": data.get("total", 0)}
+
+    async def clear_stock(self, product_id: str) -> int:
+        """Clear all stock from a product"""
+        data = await self._request("DELETE", f"/products/{quote(product_id)}/stock")
+        return data.get("cleared", 0)
+
+    # ============ Categories ============
+
+    async def get_categories(self) -> List[Category]:
+        """Get all categories"""
+        data = await self._request("GET", "/categories")
+        return [Category.from_dict(c) for c in data.get("categories", [])]
+
+    async def create_category(
+        self, *, name: str, description: Optional[str] = None, color: Optional[str] = None
+    ) -> Category:
+        """Create a new category"""
+        body: Dict[str, Any] = {"name": name}
+        if description is not None:
+            body["description"] = description
+        if color is not None:
+            body["color"] = color
+
+        data = await self._request("POST", "/categories", body)
+        return Category.from_dict(data.get("category", {}))
+
+    async def update_category(
+        self,
+        category_id: str,
+        *,
+        name: Optional[str] = None,
+        description: Optional[str] = None,
+        color: Optional[str] = None,
+    ) -> Category:
+        """Update a category"""
+        body: Dict[str, Any] = {}
+        if name is not None:
+            body["name"] = name
+        if description is not None:
+            body["description"] = description
+        if color is not None:
+            body["color"] = color
+
+        data = await self._request("PATCH", f"/categories/{quote(category_id)}", body)
+        return Category.from_dict(data.get("category", {}))
+
+    async def delete_category(self, category_id: str) -> bool:
+        """Delete a category"""
+        await self._request("DELETE", f"/categories/{quote(category_id)}")
+        return True
+
+    # ============ Grades ============
+
+    async def get_grades(self) -> List[Grade]:
+        """Get all grades"""
+        data = await self._request("GET", "/grades")
+        return [Grade.from_dict(g) for g in data.get("grades", [])]
+
+    async def create_grade(
+        self,
+        *,
+        name: str,
+        min_spend_krw: int,
+        discount_type: Optional[str] = None,
+        discount_value: Optional[int] = None,
+        color: Optional[str] = None,
+    ) -> Grade:
+        """Create a new grade"""
+        body: Dict[str, Any] = {"name": name, "minSpendKrw": min_spend_krw}
+        if discount_type is not None:
+            body["discountType"] = discount_type
+        if discount_value is not None:
+            body["discountValue"] = discount_value
+        if color is not None:
+            body["color"] = color
+
+        data = await self._request("POST", "/grades", body)
+        return Grade.from_dict(data.get("grade", {}))
+
+    async def update_grade(
+        self,
+        grade_id: str,
+        *,
+        name: Optional[str] = None,
+        min_spend_krw: Optional[int] = None,
+        discount_type: Optional[str] = None,
+        discount_value: Optional[int] = None,
+        color: Optional[str] = None,
+    ) -> Grade:
+        """Update a grade"""
+        body: Dict[str, Any] = {}
+        if name is not None:
+            body["name"] = name
+        if min_spend_krw is not None:
+            body["minSpendKrw"] = min_spend_krw
+        if discount_type is not None:
+            body["discountType"] = discount_type
+        if discount_value is not None:
+            body["discountValue"] = discount_value
+        if color is not None:
+            body["color"] = color
+
+        data = await self._request("PATCH", f"/grades/{quote(grade_id)}", body)
+        return Grade.from_dict(data.get("grade", {}))
+
+    async def delete_grade(self, grade_id: str) -> bool:
+        """Delete a grade"""
+        await self._request("DELETE", f"/grades/{quote(grade_id)}")
+        return True
+
+    # ============ Coupons ============
+
+    async def get_coupons(
+        self, *, limit: Optional[int] = None, offset: Optional[int] = None
+    ) -> List[Coupon]:
+        """Get all coupons"""
+        data = await self._request("GET", "/coupons", params={"limit": limit, "offset": offset})
+        return [Coupon.from_dict(c) for c in data.get("coupons", [])]
+
+    async def create_coupon(
+        self,
+        *,
+        code: str,
+        type: str,
+        value: int,
+        max_uses: Optional[int] = None,
+        per_user_limit: Optional[int] = None,
+        starts_at: Optional[str] = None,
+        expires_at: Optional[str] = None,
+    ) -> Coupon:
+        """Create a new coupon"""
+        body: Dict[str, Any] = {"code": code, "type": type, "value": value}
+        if max_uses is not None:
+            body["maxUses"] = max_uses
+        if per_user_limit is not None:
+            body["perUserLimit"] = per_user_limit
+        if starts_at is not None:
+            body["startsAt"] = starts_at
+        if expires_at is not None:
+            body["expiresAt"] = expires_at
+
+        data = await self._request("POST", "/coupons", body)
+        return Coupon.from_dict(data.get("coupon", {}))
+
+    async def update_coupon(
+        self,
+        coupon_id: str,
+        *,
+        is_active: Optional[bool] = None,
+        max_uses: Optional[int] = None,
+        expires_at: Optional[str] = None,
+    ) -> Coupon:
+        """Update a coupon"""
+        body: Dict[str, Any] = {}
+        if is_active is not None:
+            body["isActive"] = is_active
+        if max_uses is not None:
+            body["maxUses"] = max_uses
+        if expires_at is not None:
+            body["expiresAt"] = expires_at
+
+        data = await self._request("PATCH", f"/coupons/{quote(coupon_id)}", body)
+        return Coupon.from_dict(data.get("coupon", {}))
+
+    async def delete_coupon(self, coupon_id: str) -> bool:
+        """Delete a coupon"""
+        await self._request("DELETE", f"/coupons/{quote(coupon_id)}")
+        return True
+
+    # ============ Users ============
+
+    async def get_users(
+        self, *, limit: Optional[int] = None, offset: Optional[int] = None
+    ) -> List[User]:
+        """Get all users"""
+        data = await self._request("GET", "/users", params={"limit": limit, "offset": offset})
+        return [User.from_dict(u) for u in data.get("users", [])]
+
+    async def get_user(self, user_id: str) -> User:
+        """Get user details"""
+        data = await self._request("GET", f"/users/{quote(user_id)}")
+        return User.from_dict(data.get("user", {}))
+
+    async def adjust_balance(
+        self, user_id: str, amount: int, reason: Optional[str] = None
+    ) -> BalanceResult:
+        """Adjust user balance"""
+        body: Dict[str, Any] = {"amount": amount}
+        if reason is not None:
+            body["reason"] = reason
+
+        data = await self._request("POST", f"/users/{quote(user_id)}/balance", body)
+        return BalanceResult.from_dict(data)
+
+    async def set_grade(self, user_id: str, grade_id: Optional[str]) -> bool:
+        """Set user grade"""
+        await self._request("PUT", f"/users/{quote(user_id)}/grade", {"gradeId": grade_id})
+        return True
+
+    # ============ Charges ============
+
+    async def get_charges(
+        self,
+        *,
+        status: Optional[str] = None,
+        limit: Optional[int] = None,
+        offset: Optional[int] = None,
+    ) -> List[ChargeRequest]:
+        """Get charge requests"""
+        data = await self._request(
+            "GET", "/charges", params={"status": status, "limit": limit, "offset": offset}
+        )
+        return [ChargeRequest.from_dict(c) for c in data.get("charges", [])]
+
+    async def approve_charge(self, charge_id: str, approved_krw: Optional[int] = None) -> bool:
+        """Approve a charge request"""
+        body: Dict[str, Any] = {}
+        if approved_krw is not None:
+            body["approvedKrw"] = approved_krw
+
+        await self._request("POST", f"/charges/{quote(charge_id)}/approve", body)
+        return True
+
+    async def reject_charge(self, charge_id: str, reason: Optional[str] = None) -> bool:
+        """Reject a charge request"""
+        body: Dict[str, Any] = {}
+        if reason is not None:
+            body["reason"] = reason
+
+        await self._request("POST", f"/charges/{quote(charge_id)}/reject", body)
+        return True
+
+    # ============ Orders ============
+
+    async def get_orders(
+        self,
+        *,
+        status: Optional[str] = None,
+        user_id: Optional[str] = None,
+        limit: Optional[int] = None,
+        offset: Optional[int] = None,
+    ) -> List[Order]:
+        """Get orders"""
+        data = await self._request(
+            "GET",
+            "/orders",
+            params={"status": status, "userId": user_id, "limit": limit, "offset": offset},
+        )
+        return [Order.from_dict(o) for o in data.get("orders", [])]
+
+    async def get_order(self, order_id: str) -> Order:
+        """Get order details"""
+        data = await self._request("GET", f"/orders/{quote(order_id)}")
+        return Order.from_dict(data.get("order", {}))
+
+    # ============ Reviews ============
+
+    async def get_reviews(
+        self,
+        *,
+        product_id: Optional[str] = None,
+        limit: Optional[int] = None,
+        offset: Optional[int] = None,
+    ) -> List[Review]:
+        """Get reviews"""
+        data = await self._request(
+            "GET",
+            "/reviews",
+            params={"productId": product_id, "limit": limit, "offset": offset},
+        )
+        return [Review.from_dict(r) for r in data.get("reviews", [])]
+
+    async def hide_review(self, review_id: str, hide: bool) -> bool:
+        """Hide or unhide a review"""
+        await self._request("PATCH", f"/reviews/{quote(review_id)}", {"isHidden": hide})
+        return True
+
+    async def delete_review(self, review_id: str) -> bool:
+        """Delete a review"""
+        await self._request("DELETE", f"/reviews/{quote(review_id)}")
+        return True
+
+    # ============ Analytics ============
+
+    async def get_analytics(self, range: str = "7d") -> Analytics:
+        """Get analytics data"""
+        data = await self._request("GET", "/analytics", params={"range": range})
+        return Analytics.from_dict(data)
+
+    # ============ Settings ============
+
+    async def get_settings(self) -> Settings:
+        """Get store settings"""
+        data = await self._request("GET", "/settings")
+        return Settings.from_dict(data.get("settings", {}))
+
+    async def update_settings(
+        self,
+        *,
+        announcement: Optional[str] = None,
+        bank_charge: Optional[bool] = None,
+        giftcard_charge: Optional[bool] = None,
+        allow_guest: Optional[bool] = None,
+        allow_unverified_charge: Optional[bool] = None,
+    ) -> bool:
+        """Update store settings"""
+        body: Dict[str, Any] = {}
+        if announcement is not None:
+            body["announcement"] = announcement
+        if bank_charge is not None:
+            body["bankCharge"] = bank_charge
+        if giftcard_charge is not None:
+            body["giftcardCharge"] = giftcard_charge
+        if allow_guest is not None:
+            body["allowGuest"] = allow_guest
+        if allow_unverified_charge is not None:
+            body["allowUnverifiedCharge"] = allow_unverified_charge
+
+        await self._request("PATCH", "/settings", body)
+        return True
+
+    # ============ Webhooks ============
+
+    async def get_webhooks(self) -> List[Webhook]:
+        """Get all webhooks"""
+        data = await self._request("GET", "/webhooks")
+        return [Webhook.from_dict(w) for w in data.get("webhooks", [])]
+
+    async def create_webhook(self, *, url: str, events: List[str]) -> Webhook:
+        """Create a new webhook"""
+        data = await self._request("POST", "/webhooks", {"url": url, "events": events})
+        return Webhook.from_dict(data.get("webhook", {}))
+
+    async def delete_webhook(self, webhook_id: str) -> bool:
+        """Delete a webhook"""
+        await self._request("DELETE", f"/webhooks/{quote(webhook_id)}")
+        return True

stellavend_api/types.py

@@ -0,0 +1,380 @@
+"""
+Type definitions for StellaVend Open API
+"""
+
+from dataclasses import dataclass
+from typing import Optional, List, Dict, Any
+
+
+@dataclass
+class Store:
+    id: str
+    slug: str
+    name: str
+    description: Optional[str] = None
+    announcement: Optional[str] = None
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Store":
+        return cls(
+            id=data.get("id", ""),
+            slug=data.get("slug", ""),
+            name=data.get("name", ""),
+            description=data.get("description"),
+            announcement=data.get("announcement"),
+        )
+
+
+@dataclass
+class BulkTier:
+    min_qty: int
+    price_krw: int
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "BulkTier":
+        return cls(
+            min_qty=data.get("minQty", 0),
+            price_krw=data.get("priceKrw", 0),
+        )
+
+
+@dataclass
+class Product:
+    id: str
+    name: str
+    description: str
+    detail_text: str
+    price_krw: int
+    category_id: Optional[str]
+    bulk_tiers: List[BulkTier]
+    stock_count: int
+    is_active: bool
+    created_at: str
+    updated_at: str
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Product":
+        return cls(
+            id=data.get("id", ""),
+            name=data.get("name", ""),
+            description=data.get("description", ""),
+            detail_text=data.get("detailText", ""),
+            price_krw=data.get("priceKrw", 0),
+            category_id=data.get("categoryId"),
+            bulk_tiers=[BulkTier.from_dict(t) for t in data.get("bulkTiers", [])],
+            stock_count=data.get("stockCount", 0),
+            is_active=data.get("isActive", False),
+            created_at=data.get("createdAt", ""),
+            updated_at=data.get("updatedAt", ""),
+        )
+
+
+@dataclass
+class Category:
+    id: str
+    name: str
+    description: str
+    color: str
+    discount_type: Optional[str]
+    discount_value: int
+    sort_order: int
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Category":
+        return cls(
+            id=data.get("id", ""),
+            name=data.get("name", ""),
+            description=data.get("description", ""),
+            color=data.get("color", ""),
+            discount_type=data.get("discountType"),
+            discount_value=data.get("discountValue", 0),
+            sort_order=data.get("sortOrder", 0),
+        )
+
+
+@dataclass
+class Grade:
+    id: str
+    name: str
+    description: str
+    color: str
+    min_spend_krw: int
+    discount_type: Optional[str]
+    discount_value: int
+    sort_order: int
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Grade":
+        return cls(
+            id=data.get("id", ""),
+            name=data.get("name", ""),
+            description=data.get("description", ""),
+            color=data.get("color", ""),
+            min_spend_krw=data.get("minSpendKrw", 0),
+            discount_type=data.get("discountType"),
+            discount_value=data.get("discountValue", 0),
+            sort_order=data.get("sortOrder", 0),
+        )
+
+
+@dataclass
+class Coupon:
+    id: str
+    code: str
+    type: str
+    rule: str
+    value: int
+    min_order_krw: int
+    max_order_krw: int
+    min_quantity: int
+    max_quantity: int
+    max_discount_krw: int
+    per_user_limit: int
+    max_uses: int
+    used_count: int
+    allow_guest: bool
+    starts_at: Optional[str]
+    expires_at: Optional[str]
+    is_active: bool
+    created_at: str
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Coupon":
+        return cls(
+            id=data.get("id", ""),
+            code=data.get("code", ""),
+            type=data.get("type", ""),
+            rule=data.get("rule", ""),
+            value=data.get("value", 0),
+            min_order_krw=data.get("minOrderKrw", 0),
+            max_order_krw=data.get("maxOrderKrw", 0),
+            min_quantity=data.get("minQuantity", 0),
+            max_quantity=data.get("maxQuantity", 0),
+            max_discount_krw=data.get("maxDiscountKrw", 0),
+            per_user_limit=data.get("perUserLimit", 0),
+            max_uses=data.get("maxUses", 0),
+            used_count=data.get("usedCount", 0),
+            allow_guest=data.get("allowGuest", False),
+            starts_at=data.get("startsAt"),
+            expires_at=data.get("expiresAt"),
+            is_active=data.get("isActive", False),
+            created_at=data.get("createdAt", ""),
+        )
+
+
+@dataclass
+class User:
+    id: str
+    username: str
+    email: Optional[str]
+    balance_krw: int
+    total_spent_krw: int
+    grade_id: Optional[str]
+    grade_name: Optional[str]
+    discord_id: Optional[str]
+    created_at: str
+    last_login_at: Optional[str]
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "User":
+        return cls(
+            id=data.get("id", ""),
+            username=data.get("username", ""),
+            email=data.get("email"),
+            balance_krw=data.get("balanceKrw", 0),
+            total_spent_krw=data.get("totalSpentKrw", 0),
+            grade_id=data.get("gradeId"),
+            grade_name=data.get("gradeName"),
+            discord_id=data.get("discordId"),
+            created_at=data.get("createdAt", ""),
+            last_login_at=data.get("lastLoginAt"),
+        )
+
+
+@dataclass
+class ChargeRequest:
+    id: str
+    type: str
+    status: str
+    requested_krw: int
+    approved_krw: Optional[int]
+    user_id: str
+    username: Optional[str]
+    created_at: str
+    updated_at: str
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "ChargeRequest":
+        return cls(
+            id=data.get("id", ""),
+            type=data.get("type", ""),
+            status=data.get("status", ""),
+            requested_krw=data.get("requestedKrw", 0),
+            approved_krw=data.get("approvedKrw"),
+            user_id=data.get("userId", ""),
+            username=data.get("username"),
+            created_at=data.get("createdAt", ""),
+            updated_at=data.get("updatedAt", ""),
+        )
+
+
+@dataclass
+class Order:
+    id: str
+    product_id: str
+    product_name: str
+    quantity: int
+    unit_price_krw: int
+    total_price_krw: int
+    discount_krw: int
+    status: str
+    user_id: Optional[str]
+    username: Optional[str]
+    guest_identifier: Optional[str]
+    created_at: str
+    delivered_items: Optional[List[str]] = None
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Order":
+        return cls(
+            id=data.get("id", ""),
+            product_id=data.get("productId", ""),
+            product_name=data.get("productName", ""),
+            quantity=data.get("quantity", 0),
+            unit_price_krw=data.get("unitPriceKrw", 0),
+            total_price_krw=data.get("totalPriceKrw", 0),
+            discount_krw=data.get("discountKrw", 0),
+            status=data.get("status", ""),
+            user_id=data.get("userId"),
+            username=data.get("username"),
+            guest_identifier=data.get("guestIdentifier"),
+            created_at=data.get("createdAt", ""),
+            delivered_items=data.get("deliveredItems"),
+        )
+
+
+@dataclass
+class Review:
+    id: str
+    product_id: str
+    product_name: str
+    user_id: Optional[str]
+    username: Optional[str]
+    rating: int
+    content: str
+    is_hidden: bool
+    created_at: str
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Review":
+        return cls(
+            id=data.get("id", ""),
+            product_id=data.get("productId", ""),
+            product_name=data.get("productName", ""),
+            user_id=data.get("userId"),
+            username=data.get("username"),
+            rating=data.get("rating", 0),
+            content=data.get("content", ""),
+            is_hidden=data.get("isHidden", False),
+            created_at=data.get("createdAt", ""),
+        )
+
+
+@dataclass
+class TopProduct:
+    product_id: str
+    name: str
+    count: int
+    revenue: int
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "TopProduct":
+        return cls(
+            product_id=data.get("productId", ""),
+            name=data.get("name", ""),
+            count=data.get("count", 0),
+            revenue=data.get("revenue", 0),
+        )
+
+
+@dataclass
+class Analytics:
+    range: str
+    sales_krw: int
+    order_count: int
+    new_users: int
+    top_products: List[TopProduct]
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Analytics":
+        return cls(
+            range=data.get("range", ""),
+            sales_krw=data.get("salesKrw", 0),
+            order_count=data.get("orderCount", 0),
+            new_users=data.get("newUsers", 0),
+            top_products=[TopProduct.from_dict(p) for p in data.get("topProducts", [])],
+        )
+
+
+@dataclass
+class Settings:
+    announcement: str
+    bank_charge: bool
+    giftcard_charge: bool
+    allow_guest: bool
+    allow_unverified_charge: bool
+    discord_webhook_url: str
+    discord_log_events: List[str]
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Settings":
+        return cls(
+            announcement=data.get("announcement", ""),
+            bank_charge=data.get("bankCharge", False),
+            giftcard_charge=data.get("giftcardCharge", False),
+            allow_guest=data.get("allowGuest", False),
+            allow_unverified_charge=data.get("allowUnverifiedCharge", False),
+            discord_webhook_url=data.get("discordWebhookUrl", ""),
+            discord_log_events=data.get("discordLogEvents", []),
+        )
+
+
+@dataclass
+class Webhook:
+    id: str
+    url: str
+    events: List[str]
+    is_active: bool
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Webhook":
+        return cls(
+            id=data.get("id", ""),
+            url=data.get("url", ""),
+            events=data.get("events", []),
+            is_active=data.get("isActive", False),
+        )
+
+
+@dataclass
+class StockResult:
+    lines: List[str]
+    count: int
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "StockResult":
+        return cls(
+            lines=data.get("lines", []),
+            count=data.get("count", 0),
+        )
+
+
+@dataclass
+class BalanceResult:
+    new_balance: int
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "BalanceResult":
+        return cls(
+            new_balance=data.get("newBalance", 0),
+        )

stellavend_api_sdk-1.0.0.dist-info/METADATA

@@ -0,0 +1,222 @@
+Metadata-Version: 2.4
+Name: stellavend-api-sdk
+Version: 1.0.0
+Summary: StellaVend Open API SDK for Python
+License-Expression: MIT
+Project-URL: Homepage, https://stellavend.com
+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-api-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

stellavend_api_sdk-1.0.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+stellavend_api/__init__.py,sha256=iB6QTzEEd8DDN_WFJiVyNxTgJlR2lTQwZ2U1vFC-nWk,775
+stellavend_api/client.py,sha256=kJyqE0GR-OsgYdTMGPrBtsg3r0Rmesn-4ZFiDMeKjpg,18133
+stellavend_api/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+stellavend_api/types.py,sha256=wECeQ7LiIbpXrJLxJlNOXo0DhdoSczwud1jk9aUlPKo,10317
+stellavend_api_sdk-1.0.0.dist-info/METADATA,sha256=50xp2_SBKcaVGrEfiePcDIl_gpX1j89N6ivQL7JMHj8,4954
+stellavend_api_sdk-1.0.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+stellavend_api_sdk-1.0.0.dist-info/top_level.txt,sha256=g-ZG_NH--qWKos7-XfAScF8OzfrH0EZRLxxWA655odU,15
+stellavend_api_sdk-1.0.0.dist-info/RECORD,,

stellavend_api_sdk-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

stellavend_api_sdk-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+stellavend_api