Metadata-Version: 2.4
Name: docges-api-py
Version: 0.1.1
Summary: Async, typed Python client for DocGes REST API
Author-email: "ct.galega" <soporte@ctgalega.com>
License: MIT
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: respx>=0.22; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Dynamic: license-file

# docges-api-py

Async, typed Python client for the DocGes REST API.

> **Work in progress** — bootstrapped via SDD (Spec-Driven Development).  
> Phase 1-4 completed: async client with auth, retry, token refresh, and tests.
> Phase 5 completed: All core endpoints implemented.

## Features

- ✅ Async HTTP client using `httpx`
- ✅ Typed request/response models with Pydantic v2
- ✅ Configurable retries and timeouts
 - ✅ Session-based auth using `loginResponse` passed to Content endpoints
- ✅ Full test coverage (pytest + respx)
- ✅ Complete DocGes API client (upload, download, search, categories)

## Implemented endpoints

### Auth
- `auth()` — authenticate against `/Auth/Login`

### Content Tree
- `get_initial_cats()` — load initial categories via `/Content/LoadIniCats`
- `get_cat_info(sid)` — load category children via `/Content/LoadChilds`

### Document Operations
- `upload_file(category_sid, file_path)` — upload via `/Content/UploadExtended`
- `download_content(sid)` — download via `/Content/Download` (returns `ResFileDownload`)
- `get_document(sid)` — deprecated wrapper (calls `download_content()`)

### Search
- `search_content(field_values, date_values)` — search via `/Content/SearchContent`

### Category Management
- `create_category(parent_sid, name)` — create via `/Content/CreateCategory`
- `rename_category(sid, new_name)` — rename via `/Content/RenameCategory`
- `delete_category(sid)` — delete via `/Content/DeleteCategory`

### Document Management
- `remove_document(sid)` — remove via `/Content/RemoveDocument`
- `move_content(content_sid, destination_sid)` — move via `/Content/Move`
- `update_content(sid, erp_relation, erp_property)` — update via `/Content/Update`

## Quick start

```bash
pip install -e ".[dev]"
```

```python
import asyncio
from docges_api_py import AsyncDocGes


async def main():
    async with AsyncDocGes(
        "https://docges.example.com", "user", "password", "appid"
    ) as client:
        # Auth
        auth_resp = await client.auth()
        # The API is session-based: auth_resp contains user_info and ware_house_info
        print(f"User: {auth_resp.user_info.get('Nombre')}")
        print(f"Warehouse: {auth_resp.ware_house_info.get('Nombre')}")

        # Load initial categories (the client injects loginResponse automatically)
        cats = await client.get_initial_cats()
        print(f"Initial categories: {len(cats.CategoriasHijas)}")

        # Search documents
        results = await client.search_content(
            field_values=[{"field": "name", "mode": "contains", "text": "invoice"}]
        )
        print(f"Search results: {len(results.results)}")


asyncio.run(main())
```

See `docs/quickstart.md` or `examples/quickstart.py` for a more complete example.

## Development

```bash
pip install -e ".[dev]"
ruff check src/ tests/
mypy src/
pytest --cov=docges_api_py
```

## Migration

The library is being migrated from a sync `requests`-based client (see `wm-sync` reference code). See `docs/MIGRATION.md` for details.

Key changes:
- Replaced `requests` (sync) with `httpx.AsyncClient`
- Replaced raw `__dict__` serialization with Pydantic v2 models
- Replaced silent `return None` with typed exceptions (`AuthenticationError`, `RequestError`)
- Added configurable retries with exponential backoff

## Project structure

```
docges-api-py/
├── src/docges_api_py/
│   ├── __init__.py          # Exports AsyncDocGes, models (ResCat, ResFileDownload, etc.)
│   ├── client.py            # AsyncDocGes client (auth + all endpoints)
│   └── models/
│       ├── auth.py           # AuthRequest, AuthResponse
│       ├── document.py      # Document
│       ├── requests.py      # Request models (ReqUpload, ReqSearchContent, etc.)
│       ├── responses.py     # Response models (ResCat, ResFileDownload, etc.)
│       └── __init__.py      # Model exports
├── tests/
│   ├── conftest.py
│   ├── test_client_auth.py
│   ├── test_initial_cats.py
│   ├── test_content_methods.py
│   ├── test_remaining_methods.py
│   ├── test_models_requests.py
│   ├── test_models_responses.py
│   ├── test_models_init.py
│   ├── test_endpoints.py
│   ├── test_retry.py
│   └── test_token_refresh.py
├── examples/
│   └── quickstart.py
├── docs/
│   └── MIGRATION.md
├── pyproject.toml
├── ruff.toml
├── mypy.ini
└── README.md
```

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
