tiny-erp-py 0.1.0__py3-none-any.whl

tiny_erp_py-0.1.0.dist-info/METADATA

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: tiny-erp-py
+Version: 0.1.0
+Summary: Production-grade Python SDK for the Tiny ERP API v2
+Author: Joaoaalves
+License: MIT
+Keywords: api,erp,sdk,tiny,tiny-erp
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.0
+Requires-Dist: requests>=2.31
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-httpserver>=1.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: responses>=0.25; extra == 'dev'
+Requires-Dist: respx>=0.20; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# tiny-py
+
+> Production-grade Python SDK for the **Tiny ERP API v2**.
+> Fully typed, async-ready, and safe for FastAPI services and message queue workers.
+
+[![PyPI version](https://img.shields.io/pypi/v/tiny-erp-py.svg)](https://pypi.org/project/tiny-erp-py/)
+[![Python](https://img.shields.io/pypi/pyversions/tiny-erp-py.svg)](https://pypi.org/project/tiny-erp-py/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+---
+
+## Features
+
+- **Single entry point** — all interaction through `TinyClient` or `AsyncTinyClient`
+- **Typed contracts** — every method accepts and returns Pydantic v2 models
+- **Automatic rate limiting** — token bucket per client instance, plan-aware (30 / 60 / 120 RPM)
+- **Retry with exponential backoff** — automatic on 429 / 5xx responses
+- **Sync + Async** — `TinyClient` for workers, `AsyncTinyClient` for FastAPI
+- **No global state** — multiple tokens and plans can coexist in the same process
+
+## Installation
+
+```bash
+pip install tiny-py
+```
+
+Requires Python 3.11+.
+
+## Quick example
+
+```python
+from tiny_py import TinyClient
+
+client = TinyClient(token="your_token", plan="advanced")
+
+# Stream all active products
+for product in client.products.iter_search():
+    print(product.sku, product.name, product.price)
+
+# Fetch a single order
+order = client.orders.get("970977594")
+print(order.number, order.total)
+```
+
+### Async (FastAPI)
+
+```python
+from tiny_py import AsyncTinyClient
+
+async with AsyncTinyClient(token="your_token", plan="advanced") as client:
+    products = await client.products.search()
+    order = await client.orders.get("970977594")
+```
+
+## API coverage (v0.1.0)
+
+| Resource | Methods |
+|----------|---------|
+| **Products** | `search`, `iter_search`, `get`, `get_stock`, `update_stock`, `update_price` |
+| **Orders** | `search`, `iter_search`, `get` |
+
+See the [roadmap](https://github.com/your-org/tiny-py) for planned resources.
+
+## Error handling
+
+```python
+from tiny_py.exceptions import TinyAPIError, TinyRateLimitError, TinyServerError, TinyTimeoutError
+
+try:
+    order = client.orders.get(order_id)
+except TinyAPIError:
+    # Business error — do not retry (send to DLQ)
+    ...
+except (TinyRateLimitError, TinyServerError, TinyTimeoutError):
+    # Transient error — re-enqueue with backoff
+    ...
+```
+
+## License
+
+MIT

tiny_erp_py-0.1.0.dist-info/RECORD

@@ -0,0 +1,20 @@
+tiny_py/__init__.py,sha256=b1gPw92cDAC4CjiLN8aG6hEkrSVPrkF--qNSL1Tplso,188
+tiny_py/_async_http.py,sha256=Cl1gH5tMMIrboTyQf2xC6QKpvWRetfq6PKHHgLlLeUI,4848
+tiny_py/_client.py,sha256=DDRu0xbHnJmy-7r14Eb98tn-W5vjXfJYV--8U0jf0D4,3359
+tiny_py/_http.py,sha256=u0-kHyItwkr2MaRh0BrBQ2tdg1CM4j1Sc-WkMJeoXg8,5665
+tiny_py/_rate_limiter.py,sha256=N1RRkPD0ko0Er39I_x-S48km_PaSRqKFBgccOUVXGCo,2101
+tiny_py/exceptions.py,sha256=L9KcgdnZCbrdYYPViM9Qynezu_mJ8IZO41nOODqFm5U,750
+tiny_py/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tiny_py/models/__init__.py,sha256=znKw9DF6F-0krR1Lh2mvjacoE9nmJGcvlH2QD4O6vFE,468
+tiny_py/models/order.py,sha256=m0WaL4aSWgEQssbmoGIPOT4uR9buVSephaWBnwXlri8,1411
+tiny_py/models/product.py,sha256=v5Wy8O-5K1gVn40k81wEbP5p_MVTl6aWlN_f8wEuMqY,1953
+tiny_py/resources/__init__.py,sha256=nMJ3Pf6xYn3anZ25AGcggzibWQIXNyt8aCWCl83egM4,162
+tiny_py/resources/_async_base.py,sha256=pEb1MtEdjvVKC9fkFvrCpH9hTC9aQkFyd-Bn24J0Z-4,1181
+tiny_py/resources/_base.py,sha256=dWTvEjDSFLbbxGdgQSD6i9NrwQzStoTMVE_V0fFEm5Y,1132
+tiny_py/resources/async_orders.py,sha256=CpP0xDfUJN6x2fJf_M3UrwSpDcdOZjr1VMmiDKKr7QA,1241
+tiny_py/resources/async_products.py,sha256=dBOZxMj-Bhf5QgyxiUd2OYUTUmxjP1m_9OqFktVm7d4,2416
+tiny_py/resources/orders.py,sha256=td6vVMKabnz1hZw6Hs5LJQyQ6I_xCFRZQKmVWfAxtH0,1200
+tiny_py/resources/products.py,sha256=1T8bZu9nt9Skww0RQ3uBE6QkTUSVWvN_h8cY-doPlVE,2339
+tiny_erp_py-0.1.0.dist-info/METADATA,sha256=5mtk33Ohir-lneDiOuVBUUu3kcKGdwBNEM2nr-ZK3XE,3357
+tiny_erp_py-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+tiny_erp_py-0.1.0.dist-info/RECORD,,

tiny_erp_py-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

tiny_py/__init__.py

@@ -0,0 +1,5 @@
+from tiny_py._client import AsyncTinyClient, TinyClient
+from tiny_py import exceptions
+from tiny_py import models
+
+__all__ = ["TinyClient", "AsyncTinyClient", "exceptions", "models"]

tiny_py/_async_http.py

@@ -0,0 +1,135 @@
+import asyncio
+import time
+from typing import Any
+
+import httpx
+
+from tiny_py._rate_limiter import AsyncRateLimiter
+from tiny_py.exceptions import (
+    TinyAPIError,
+    TinyAuthError,
+    TinyRateLimitError,
+    TinyServerError,
+    TinyTimeoutError,
+)
+
+_RETRYABLE_STATUS = frozenset({429, 500, 502, 503, 504})
+
+
+class AsyncHTTPAdapter:
+    def __init__(
+        self,
+        token: str,
+        rate_limiter: AsyncRateLimiter,
+        timeout: tuple[float, float],
+        max_retries: int,
+        base_url: str,
+    ) -> None:
+        self._token = token
+        self._rate_limiter = rate_limiter
+        self._timeout = httpx.Timeout(timeout[1], connect=timeout[0])
+        self._max_retries = max_retries
+        self._base_url = base_url.rstrip("/")
+        self._client = httpx.AsyncClient()
+
+    def _url(self, endpoint: str) -> str:
+        return f"{self._base_url}/{endpoint.lstrip('/')}"
+
+    def _base_params(self) -> dict[str, str]:
+        return {"token": self._token, "formato": "json"}
+
+    def _parse_retorno(self, data: dict[str, Any], endpoint: str) -> dict[str, Any]:
+        retorno: dict[str, Any] = data.get("retorno", {})
+        status = retorno.get("status", "").lower()
+        if status != "ok":
+            erros_raw = retorno.get("erros", [])
+            errors: list[str] = []
+            for e in erros_raw:
+                if isinstance(e, dict):
+                    errors.append(e.get("erro", str(e)))
+                else:
+                    errors.append(str(e))
+            message = errors[0] if errors else "Unknown error"
+            if any(
+                "token" in err.lower()
+                or "autenticação" in err.lower()
+                or "autenticacao" in err.lower()
+                for err in errors
+            ):
+                raise TinyAuthError(message, endpoint, errors)
+            raise TinyAPIError(message, endpoint, errors)
+        return retorno
+
+    async def _request_with_retry(
+        self, method: str, endpoint: str, **kwargs: Any
+    ) -> dict[str, Any]:
+        url = self._url(endpoint)
+        backoff = 1.0
+        last_exc: Exception | None = None
+
+        for attempt in range(self._max_retries + 1):
+            if attempt > 0:
+                await asyncio.sleep(backoff)
+                backoff = min(backoff * 2, 60.0)
+
+            await self._rate_limiter.acquire()
+
+            try:
+                resp = await self._client.request(
+                    method, url, timeout=self._timeout, **kwargs
+                )
+            except httpx.TimeoutException as exc:
+                last_exc = exc
+                if attempt >= self._max_retries:
+                    raise TinyTimeoutError(
+                        f"Request to {endpoint} timed out"
+                    ) from exc
+                continue
+            except httpx.RequestError as exc:
+                raise TinyServerError(f"Request failed: {exc}") from exc
+
+            if resp.status_code in _RETRYABLE_STATUS:
+                if attempt < self._max_retries:
+                    last_exc = (
+                        TinyRateLimitError(f"Rate limit on {endpoint}")
+                        if resp.status_code == 429
+                        else TinyServerError(f"Server error on {endpoint}")
+                    )
+                    continue
+                if resp.status_code == 429:
+                    raise TinyRateLimitError(
+                        f"Rate limit exceeded on {endpoint} after {self._max_retries + 1} attempts"
+                    )
+                raise TinyServerError(
+                    f"Server error {resp.status_code} on {endpoint} after {self._max_retries + 1} attempts"
+                )
+
+            try:
+                resp.raise_for_status()
+            except httpx.HTTPStatusError as exc:
+                raise TinyServerError(f"HTTP error on {endpoint}: {exc}") from exc
+
+            return self._parse_retorno(resp.json(), endpoint)
+
+        if last_exc is not None:
+            raise last_exc
+        raise TinyServerError(
+            f"All {self._max_retries + 1} attempts failed for {endpoint}"
+        )
+
+    async def get(
+        self, endpoint: str, params: dict[str, Any] | None = None
+    ) -> dict[str, Any]:
+        all_params = {**self._base_params(), **(params or {})}
+        return await self._request_with_retry("GET", endpoint, params=all_params)
+
+    async def post(
+        self, endpoint: str, data: dict[str, Any] | None = None
+    ) -> dict[str, Any]:
+        all_params = self._base_params()
+        return await self._request_with_retry(
+            "POST", endpoint, params=all_params, data=data or {}
+        )
+
+    async def close(self) -> None:
+        await self._client.aclose()

tiny_py/_client.py

@@ -0,0 +1,105 @@
+from typing import TYPE_CHECKING, Literal
+
+from tiny_py._http import HTTPAdapter
+from tiny_py._rate_limiter import PLAN_RPM, AsyncRateLimiter, RateLimiter
+from tiny_py.resources.orders import OrdersResource
+from tiny_py.resources.products import ProductsResource
+
+if TYPE_CHECKING:
+    from tiny_py._async_http import AsyncHTTPAdapter
+    from tiny_py.resources.async_orders import AsyncOrdersResource
+    from tiny_py.resources.async_products import AsyncProductsResource
+
+Plan = Literal["free", "basic", "advanced"]
+
+DEFAULT_BASE_URL = "https://api.tiny.com.br/api2"
+DEFAULT_TIMEOUT: tuple[float, float] = (5.0, 30.0)
+DEFAULT_MAX_RETRIES = 3
+
+
+class TinyClient:
+    def __init__(
+        self,
+        token: str,
+        plan: Plan = "advanced",
+        timeout: tuple[float, float] = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        base_url: str = DEFAULT_BASE_URL,
+    ) -> None:
+        rpm = PLAN_RPM[plan]
+        self._http = HTTPAdapter(
+            token=token,
+            rate_limiter=RateLimiter(rpm),
+            timeout=timeout,
+            max_retries=max_retries,
+            base_url=base_url,
+        )
+        self._products: ProductsResource | None = None
+        self._orders: OrdersResource | None = None
+
+    @property
+    def products(self) -> ProductsResource:
+        if self._products is None:
+            self._products = ProductsResource(self._http)
+        return self._products
+
+    @property
+    def orders(self) -> OrdersResource:
+        if self._orders is None:
+            self._orders = OrdersResource(self._http)
+        return self._orders
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "TinyClient":
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+
+class AsyncTinyClient:
+    def __init__(
+        self,
+        token: str,
+        plan: Plan = "advanced",
+        timeout: tuple[float, float] = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        base_url: str = DEFAULT_BASE_URL,
+    ) -> None:
+        from tiny_py._async_http import AsyncHTTPAdapter
+
+        rpm = PLAN_RPM[plan]
+        self._http: AsyncHTTPAdapter = AsyncHTTPAdapter(
+            token=token,
+            rate_limiter=AsyncRateLimiter(rpm),
+            timeout=timeout,
+            max_retries=max_retries,
+            base_url=base_url,
+        )
+        self._products: AsyncProductsResource | None = None
+        self._orders: AsyncOrdersResource | None = None
+
+    @property
+    def products(self) -> "AsyncProductsResource":
+        if self._products is None:
+            from tiny_py.resources.async_products import AsyncProductsResource
+            self._products = AsyncProductsResource(self._http)
+        return self._products
+
+    @property
+    def orders(self) -> "AsyncOrdersResource":
+        if self._orders is None:
+            from tiny_py.resources.async_orders import AsyncOrdersResource
+            self._orders = AsyncOrdersResource(self._http)
+        return self._orders
+
+    async def close(self) -> None:
+        await self._http.close()
+
+    async def __aenter__(self) -> "AsyncTinyClient":
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.close()

tiny_py/_http.py

@@ -0,0 +1,160 @@
+import time
+from typing import Any
+
+import requests
+from requests.adapters import HTTPAdapter as RequestsHTTPAdapter
+
+from tiny_py._rate_limiter import RateLimiter
+from tiny_py.exceptions import (
+    TinyAPIError,
+    TinyAuthError,
+    TinyRateLimitError,
+    TinyServerError,
+    TinyTimeoutError,
+)
+
+_RETRYABLE_STATUS = frozenset({429, 500, 502, 503, 504})
+
+
+class HTTPAdapter:
+    def __init__(
+        self,
+        token: str,
+        rate_limiter: RateLimiter,
+        timeout: tuple[float, float],
+        max_retries: int,
+        base_url: str,
+    ) -> None:
+        self._token = token
+        self._rate_limiter = rate_limiter
+        self._timeout = timeout
+        self._max_retries = max_retries
+        self._base_url = base_url.rstrip("/")
+        self._session = self._build_session()
+
+    def _build_session(self) -> requests.Session:
+        session = requests.Session()
+        adapter = RequestsHTTPAdapter(
+            pool_connections=4,
+            pool_maxsize=10,
+        )
+        session.mount("https://", adapter)
+        session.mount("http://", adapter)
+        return session
+
+    def _url(self, endpoint: str) -> str:
+        return f"{self._base_url}/{endpoint.lstrip('/')}"
+
+    def _base_params(self) -> dict[str, str]:
+        return {"token": self._token, "formato": "json"}
+
+    def _parse_retorno(self, response: requests.Response, endpoint: str) -> dict[str, Any]:
+        data: dict[str, Any] = response.json()
+        retorno: dict[str, Any] = data.get("retorno", {})
+        status = retorno.get("status", "").lower()
+        if status != "ok":
+            erros_raw = retorno.get("erros", [])
+            errors: list[str] = []
+            for e in erros_raw:
+                if isinstance(e, dict):
+                    errors.append(e.get("erro", str(e)))
+                else:
+                    errors.append(str(e))
+            message = (
+                errors[0]
+                if errors
+                else retorno.get("status_processamento", "Unknown error")
+            )
+            if any(
+                "token" in err.lower()
+                or "autenticação" in err.lower()
+                or "autenticacao" in err.lower()
+                for err in errors
+            ):
+                raise TinyAuthError(message, endpoint, errors)
+            raise TinyAPIError(message, endpoint, errors)
+        return retorno
+
+    def _request_with_retry(
+        self, method: str, endpoint: str, **kwargs: Any
+    ) -> dict[str, Any]:
+        url = self._url(endpoint)
+        last_exc: Exception | None = None
+        backoff = 1.0
+
+        for attempt in range(self._max_retries + 1):
+            if attempt > 0:
+                time.sleep(backoff)
+                backoff = min(backoff * 2, 60.0)
+
+            self._rate_limiter.acquire()
+
+            try:
+                resp = self._session.request(
+                    method, url, timeout=self._timeout, **kwargs
+                )
+            except requests.exceptions.Timeout as exc:
+                last_exc = exc
+                if attempt >= self._max_retries:
+                    raise TinyTimeoutError(
+                        f"Request to {endpoint} timed out"
+                    ) from exc
+                continue
+            except requests.exceptions.RequestException as exc:
+                raise TinyServerError(f"Request failed: {exc}") from exc
+
+            if resp.status_code in _RETRYABLE_STATUS:
+                if attempt < self._max_retries:
+                    last_exc = (
+                        TinyRateLimitError(f"Rate limit on {endpoint}")
+                        if resp.status_code == 429
+                        else TinyServerError(f"Server error on {endpoint}")
+                    )
+                    continue
+                # Last attempt — raise the appropriate error
+                if resp.status_code == 429:
+                    raise TinyRateLimitError(
+                        f"Rate limit exceeded on {endpoint} after {self._max_retries + 1} attempts"
+                    )
+                raise TinyServerError(
+                    f"Server error {resp.status_code} on {endpoint} after {self._max_retries + 1} attempts"
+                )
+
+            # Non-retryable status: let _parse_retorno handle business errors
+            # or raise for unexpected HTTP errors
+            try:
+                resp.raise_for_status()
+            except requests.exceptions.HTTPError as exc:
+                raise TinyServerError(f"HTTP error on {endpoint}: {exc}") from exc
+
+            return self._parse_retorno(resp, endpoint)
+
+        # Should never reach here but be safe
+        if last_exc is not None:
+            raise last_exc
+        raise TinyServerError(
+            f"All {self._max_retries + 1} attempts failed for {endpoint}"
+        )
+
+    def get(
+        self, endpoint: str, params: dict[str, Any] | None = None
+    ) -> dict[str, Any]:
+        all_params = {**self._base_params(), **(params or {})}
+        return self._request_with_retry("GET", endpoint, params=all_params)
+
+    def post(
+        self, endpoint: str, data: dict[str, Any] | None = None
+    ) -> dict[str, Any]:
+        all_params = self._base_params()
+        return self._request_with_retry(
+            "POST", endpoint, params=all_params, data=data or {}
+        )
+
+    def close(self) -> None:
+        self._session.close()
+
+    def __enter__(self) -> "HTTPAdapter":
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()

tiny_py/_rate_limiter.py

@@ -0,0 +1,65 @@
+import asyncio
+import threading
+import time
+
+PLAN_RPM: dict[str, int] = {
+    "free": 30,
+    "basic": 60,
+    "advanced": 120,
+}
+
+
+class RateLimiter:
+    """Thread-safe token bucket for synchronous use."""
+
+    def __init__(self, rpm: int) -> None:
+        self._rate = rpm / 60.0  # tokens per second
+        self._tokens: float = float(rpm)
+        self._max_tokens: float = float(rpm)
+        self._last_refill: float = time.monotonic()
+        self._lock = threading.Lock()
+
+    def acquire(self) -> None:
+        """Block until a token is available."""
+        while True:
+            with self._lock:
+                now = time.monotonic()
+                elapsed = now - self._last_refill
+                self._tokens = min(
+                    self._max_tokens,
+                    self._tokens + elapsed * self._rate,
+                )
+                self._last_refill = now
+                if self._tokens >= 1.0:
+                    self._tokens -= 1.0
+                    return
+                wait = (1.0 - self._tokens) / self._rate
+            time.sleep(wait)
+
+
+class AsyncRateLimiter:
+    """asyncio-safe token bucket for async use."""
+
+    def __init__(self, rpm: int) -> None:
+        self._rate = rpm / 60.0
+        self._tokens: float = float(rpm)
+        self._max_tokens: float = float(rpm)
+        self._last_refill: float = time.monotonic()
+        self._lock = asyncio.Lock()
+
+    async def acquire(self) -> None:
+        """Async-safe wait until a token is available."""
+        while True:
+            async with self._lock:
+                now = time.monotonic()
+                elapsed = now - self._last_refill
+                self._tokens = min(
+                    self._max_tokens,
+                    self._tokens + elapsed * self._rate,
+                )
+                self._last_refill = now
+                if self._tokens >= 1.0:
+                    self._tokens -= 1.0
+                    return
+                wait = (1.0 - self._tokens) / self._rate
+            await asyncio.sleep(wait)

tiny_py/exceptions.py

@@ -0,0 +1,27 @@
+class TinyError(Exception):
+    """Base for all tiny-py errors."""
+
+
+class TinyAPIError(TinyError):
+    """The API returned status != OK. Business-level error — do not retry."""
+
+    def __init__(self, message: str, endpoint: str, errors: list[str]) -> None:
+        super().__init__(message)
+        self.endpoint = endpoint
+        self.errors = errors
+
+
+class TinyAuthError(TinyAPIError):
+    """Invalid or expired token."""
+
+
+class TinyRateLimitError(TinyError):
+    """HTTP 429 received after all retry attempts are exhausted."""
+
+
+class TinyServerError(TinyError):
+    """HTTP 5xx after all retry attempts are exhausted."""
+
+
+class TinyTimeoutError(TinyError):
+    """Request timed out after all retry attempts."""

tiny_py/models/__init__.py

@@ -0,0 +1,25 @@
+from tiny_py.models.product import (
+    Product,
+    ProductStock,
+    StockDeposit,
+    StockDepositUpdate,
+    StockUpdateRequest,
+    PriceUpdateRequest,
+)
+from tiny_py.models.order import (
+    Order,
+    OrderItem,
+    OrderEcommerce,
+)
+
+__all__ = [
+    "Product",
+    "ProductStock",
+    "StockDeposit",
+    "StockDepositUpdate",
+    "StockUpdateRequest",
+    "PriceUpdateRequest",
+    "Order",
+    "OrderItem",
+    "OrderEcommerce",
+]

tiny_py/models/order.py

@@ -0,0 +1,41 @@
+from datetime import date
+from pydantic import BaseModel, Field, field_validator
+
+
+class OrderItem(BaseModel):
+    model_config = {"populate_by_name": True}
+
+    product_id: str = Field(alias="id_produto")
+    sku: str = Field(alias="codigo")
+    description: str = Field(alias="descricao")
+    quantity: float = Field(alias="quantidade")
+    unit_price: float = Field(alias="valor_unitario")
+
+
+class OrderEcommerce(BaseModel):
+    model_config = {"populate_by_name": True}
+
+    id: str
+    name: str = Field(alias="nomeEcommerce")
+    order_number: str = Field(alias="numeroPedidoEcommerce")
+
+
+class Order(BaseModel):
+    model_config = {"populate_by_name": True}
+
+    id: str
+    number: str = Field(alias="numero")
+    order_date: date = Field(alias="data_pedido")
+    status: str = Field(alias="situacao")
+    items: list[OrderItem] = Field(alias="itens", default_factory=list)
+    ecommerce: OrderEcommerce | None = Field(alias="ecommerce", default=None)
+    total: float = Field(alias="total_pedido")
+    tracking_code: str = Field(alias="codigo_rastreamento", default="")
+
+    @field_validator("order_date", mode="before")
+    @classmethod
+    def parse_date(cls, v: object) -> date:
+        if isinstance(v, str):
+            from datetime import datetime
+            return datetime.strptime(v, "%d/%m/%Y").date()
+        return v  # type: ignore[return-value]

tiny_py/models/product.py

@@ -0,0 +1,61 @@
+from pydantic import BaseModel, Field, field_validator
+
+
+class StockDeposit(BaseModel):
+    model_config = {"populate_by_name": True}
+
+    name: str = Field(alias="nome")
+    balance: float = Field(alias="saldo")
+    ignore: bool = Field(alias="desconsiderar")
+    company: str = Field(alias="empresa")
+
+    @field_validator("ignore", mode="before")
+    @classmethod
+    def parse_sn(cls, v: object) -> bool:
+        if isinstance(v, str):
+            return v.upper() == "S"
+        return bool(v)
+
+
+class StockDepositUpdate(BaseModel):
+    model_config = {"populate_by_name": True}
+
+    deposit_id: str = Field(alias="idDeposito")
+    balance: float = Field(alias="saldo")
+
+
+class ProductStock(BaseModel):
+    model_config = {"populate_by_name": True}
+
+    product_id: str = Field(alias="id")
+    sku: str = Field(alias="codigo")
+    name: str = Field(alias="nome")
+    balance: float = Field(alias="saldo")
+    reserved_balance: float = Field(alias="saldoReservado")
+    deposits: list[StockDeposit] = Field(alias="depositos", default_factory=list)
+
+
+class Product(BaseModel):
+    model_config = {"populate_by_name": True}
+
+    id: str
+    name: str = Field(alias="nome")
+    sku: str = Field(alias="codigo")
+    price: float = Field(alias="preco")
+    promo_price: float | None = Field(alias="preco_promocional", default=None)
+    cost_price: float | None = Field(alias="preco_custo", default=None)
+    unit: str = Field(alias="unidade")
+    gtin: str | None = Field(alias="gtin", default=None)
+    ncm: str | None = Field(alias="ncm", default=None)
+    status: str = Field(alias="situacao")
+    category: str | None = Field(alias="categoria", default=None)
+    brand: str | None = Field(alias="marca", default=None)
+
+
+class StockUpdateRequest(BaseModel):
+    deposits: list[StockDepositUpdate]
+
+
+class PriceUpdateRequest(BaseModel):
+    price: float
+    promo_price: float | None = None

tiny_py/resources/__init__.py

@@ -0,0 +1,4 @@
+from tiny_py.resources.products import ProductsResource
+from tiny_py.resources.orders import OrdersResource
+
+__all__ = ["ProductsResource", "OrdersResource"]

tiny_py/resources/_async_base.py

@@ -0,0 +1,35 @@
+from collections.abc import AsyncIterator
+from typing import Any, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from tiny_py._async_http import AsyncHTTPAdapter
+
+
+class AsyncBaseResource:
+    def __init__(self, http: "AsyncHTTPAdapter") -> None:
+        self._http = http
+
+    async def _paginate(
+        self,
+        endpoint: str,
+        collection_key: str,
+        item_key: str,
+        params: dict[str, Any],
+    ) -> AsyncIterator[dict[str, Any]]:
+        """
+        Generic async pagination iterator. Yields raw item dicts page by page.
+        Stops when the current page equals numero_paginas.
+        """
+        page = 1
+        while True:
+            retorno = await self._http.get(endpoint, {**params, "pagina": page})
+            numero_paginas = int(retorno.get("numero_paginas", 1))
+            collection = retorno.get(collection_key, [])
+            for wrapper in collection:
+                if isinstance(wrapper, dict) and item_key in wrapper:
+                    yield wrapper[item_key]
+                else:
+                    yield wrapper
+            if page >= numero_paginas:
+                break
+            page += 1

tiny_py/resources/_base.py

@@ -0,0 +1,35 @@
+from collections.abc import Iterator
+from typing import Any, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from tiny_py._http import HTTPAdapter
+
+
+class BaseResource:
+    def __init__(self, http: "HTTPAdapter") -> None:
+        self._http = http
+
+    def _paginate(
+        self,
+        endpoint: str,
+        collection_key: str,
+        item_key: str,
+        params: dict[str, Any],
+    ) -> Iterator[dict[str, Any]]:
+        """
+        Generic pagination iterator. Yields raw item dicts page by page.
+        Stops when the current page equals numero_paginas.
+        """
+        page = 1
+        while True:
+            retorno = self._http.get(endpoint, {**params, "pagina": page})
+            numero_paginas = int(retorno.get("numero_paginas", 1))
+            collection = retorno.get(collection_key, [])
+            for wrapper in collection:
+                if isinstance(wrapper, dict) and item_key in wrapper:
+                    yield wrapper[item_key]
+                else:
+                    yield wrapper
+            if page >= numero_paginas:
+                break
+            page += 1

tiny_py/resources/async_orders.py

@@ -0,0 +1,30 @@
+from collections.abc import AsyncIterator
+from datetime import date
+
+from tiny_py.models.order import Order
+from tiny_py.resources._async_base import AsyncBaseResource
+
+
+class AsyncOrdersResource(AsyncBaseResource):
+    async def search(self, date_from: date, date_to: date) -> list[Order]:
+        """Returns all orders in the date range (auto-paginated)."""
+        return [o async for o in self.iter_search(date_from=date_from, date_to=date_to)]
+
+    async def iter_search(self, date_from: date, date_to: date) -> AsyncIterator[Order]:
+        """Memory-efficient async generator."""
+        params = {
+            "dataInicial": date_from.strftime("%d/%m/%Y"),
+            "dataFinal": date_to.strftime("%d/%m/%Y"),
+        }
+        async for item in self._paginate(
+            endpoint="pedido.pesquisa.php",
+            collection_key="pedidos",
+            item_key="pedido",
+            params=params,
+        ):
+            yield Order.model_validate(item)
+
+    async def get(self, order_id: str) -> Order:
+        """Fetches full order details (pedido.obter.php)."""
+        retorno = await self._http.get("pedido.obter.php", {"id": order_id})
+        return Order.model_validate(retorno["pedido"])

tiny_py/resources/async_products.py

@@ -0,0 +1,57 @@
+import json
+from collections.abc import AsyncIterator
+
+from tiny_py.models.product import (
+    PriceUpdateRequest,
+    Product,
+    ProductStock,
+    StockUpdateRequest,
+)
+from tiny_py.resources._async_base import AsyncBaseResource
+
+
+class AsyncProductsResource(AsyncBaseResource):
+    async def search(self, situacao: str = "A") -> list[Product]:
+        """Returns all products matching the filter (auto-paginated)."""
+        return [p async for p in self.iter_search(situacao=situacao)]
+
+    async def iter_search(self, situacao: str = "A") -> AsyncIterator[Product]:
+        """Memory-efficient async generator. Preferred for large catalogues."""
+        async for item in self._paginate(
+            endpoint="produto.pesquisa.php",
+            collection_key="produtos",
+            item_key="produto",
+            params={"situacao": situacao},
+        ):
+            yield Product.model_validate(item)
+
+    async def get(self, product_id: str) -> Product:
+        """Fetches full product data (produto.obter.php)."""
+        retorno = await self._http.get("produto.obter.php", {"id": product_id})
+        return Product.model_validate(retorno["produto"])
+
+    async def get_stock(self, product_id: str) -> ProductStock:
+        """Fetches stock per deposit (produto.obter.estoque.php)."""
+        retorno = await self._http.get("produto.obter.estoque.php", {"id": product_id})
+        return ProductStock.model_validate(retorno["produto"])
+
+    async def update_stock(self, product_id: str, request: StockUpdateRequest) -> None:
+        """Updates deposit balances (produto.atualizar.estoque.php)."""
+        deposits_data = [
+            {"idDeposito": d.deposit_id, "saldo": d.balance}
+            for d in request.deposits
+        ]
+        await self._http.post(
+            "produto.atualizar.estoque.php",
+            {
+                "id": product_id,
+                "depositos": json.dumps(deposits_data),
+            },
+        )
+
+    async def update_price(self, product_id: str, request: PriceUpdateRequest) -> None:
+        """Updates regular and promotional prices (produto.atualizar.preco.php)."""
+        data: dict = {"id": product_id, "preco": request.price}
+        if request.promo_price is not None:
+            data["preco_promocional"] = request.promo_price
+        await self._http.post("produto.atualizar.preco.php", data)

tiny_py/resources/orders.py

@@ -0,0 +1,31 @@
+from collections.abc import Iterator
+from datetime import date
+
+from tiny_py._http import HTTPAdapter
+from tiny_py.models.order import Order
+from tiny_py.resources._base import BaseResource
+
+
+class OrdersResource(BaseResource):
+    def search(self, date_from: date, date_to: date) -> list[Order]:
+        """Returns all orders in the date range (auto-paginated)."""
+        return list(self.iter_search(date_from=date_from, date_to=date_to))
+
+    def iter_search(self, date_from: date, date_to: date) -> Iterator[Order]:
+        """Memory-efficient generator."""
+        params = {
+            "dataInicial": date_from.strftime("%d/%m/%Y"),
+            "dataFinal": date_to.strftime("%d/%m/%Y"),
+        }
+        for item in self._paginate(
+            endpoint="pedido.pesquisa.php",
+            collection_key="pedidos",
+            item_key="pedido",
+            params=params,
+        ):
+            yield Order.model_validate(item)
+
+    def get(self, order_id: str) -> Order:
+        """Fetches full order details (pedido.obter.php)."""
+        retorno = self._http.get("pedido.obter.php", {"id": order_id})
+        return Order.model_validate(retorno["pedido"])

tiny_py/resources/products.py

@@ -0,0 +1,58 @@
+import json
+from collections.abc import Iterator
+
+from tiny_py._http import HTTPAdapter
+from tiny_py.models.product import (
+    PriceUpdateRequest,
+    Product,
+    ProductStock,
+    StockUpdateRequest,
+)
+from tiny_py.resources._base import BaseResource
+
+
+class ProductsResource(BaseResource):
+    def search(self, situacao: str = "A") -> list[Product]:
+        """Returns all products matching the filter (auto-paginated)."""
+        return list(self.iter_search(situacao=situacao))
+
+    def iter_search(self, situacao: str = "A") -> Iterator[Product]:
+        """Memory-efficient generator. Preferred for large catalogues."""
+        for item in self._paginate(
+            endpoint="produto.pesquisa.php",
+            collection_key="produtos",
+            item_key="produto",
+            params={"situacao": situacao},
+        ):
+            yield Product.model_validate(item)
+
+    def get(self, product_id: str) -> Product:
+        """Fetches full product data (produto.obter.php)."""
+        retorno = self._http.get("produto.obter.php", {"id": product_id})
+        return Product.model_validate(retorno["produto"])
+
+    def get_stock(self, product_id: str) -> ProductStock:
+        """Fetches stock per deposit (produto.obter.estoque.php)."""
+        retorno = self._http.get("produto.obter.estoque.php", {"id": product_id})
+        return ProductStock.model_validate(retorno["produto"])
+
+    def update_stock(self, product_id: str, request: StockUpdateRequest) -> None:
+        """Updates deposit balances (produto.atualizar.estoque.php)."""
+        deposits_data = [
+            {"idDeposito": d.deposit_id, "saldo": d.balance}
+            for d in request.deposits
+        ]
+        self._http.post(
+            "produto.atualizar.estoque.php",
+            {
+                "id": product_id,
+                "depositos": json.dumps(deposits_data),
+            },
+        )
+
+    def update_price(self, product_id: str, request: PriceUpdateRequest) -> None:
+        """Updates regular and promotional prices (produto.atualizar.preco.php)."""
+        data: dict = {"id": product_id, "preco": request.price}
+        if request.promo_price is not None:
+            data["preco_promocional"] = request.promo_price
+        self._http.post("produto.atualizar.preco.php", data)