Metadata-Version: 2.4
Name: kamy-sdk
Version: 0.1.2
Summary: Kamy PDF generation API — Python SDK
Project-URL: Homepage, https://kamy.dev
Project-URL: Documentation, https://kamy.dev/docs
Project-URL: Repository, https://github.com/Kamy-Development/kamy-plugin
Project-URL: Issues, https://github.com/Kamy-Development/kamy-plugin/issues
Author-email: Kamy Development <support@kamy.dev>
License: MIT
Keywords: document-generation,invoice,kamy,mcp,pdf
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Requires-Dist: httpx>=0.25
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1; extra == 'dev'
Description-Content-Type: text/markdown

# Kamy — Python SDK

Official Python SDK for the [Kamy PDF generation API](https://kamy.dev).

```bash
pip install kamy-sdk
```

> Distribution name on PyPI is `kamy-sdk` (the `kamy` name was unavailable). The import path is still `from kamy import Kamy` — the directory under `site-packages/` is named `kamy/`, so module imports look the way you'd expect.

## Quick start

```python
from kamy import Kamy

kamy = Kamy(api_key="kamy_pk_...")  # or set KAMY_API_KEY in the env

pdf = kamy.render(
    template="invoice",
    data={
        "invoiceNumber": "INV-001",
        "from": {"name": "Acme Inc."},
        "to": {"name": "Globex Corp."},
        "lineItems": [
            {"description": "Consulting", "quantity": 10, "unitPrice": 150, "amount": 1500},
        ],
        "subtotal": 1500,
        "total": 1500,
        "currency": "USD",
    },
)

print(pdf.url)  # signed URL valid for 1 hour
```

## Async (FastAPI / asyncio)

```python
from kamy import AsyncKamy

async with AsyncKamy(api_key="kamy_pk_...") as kamy:
    pdf = await kamy.render(template="invoice", data={...})
```

## Other modes

```python
# Inline HTML
kamy.render(html="<h1>Hello {{name}}</h1>", data={"name": "world"})

# URL mode (paid plans only — fetches the URL server-side)
kamy.render(url="https://example.com/invoice/123")

# Word (.docx) output instead of PDF
kamy.render_docx(template="invoice", data={...})

# Batch — up to 100 items, partial failures don't abort
results = kamy.render_batch([
    {"template": "receipt", "data": order1},
    {"template": "receipt", "data": order2},
])
```

## Render options

```python
from kamy import Kamy, RenderOptions, FormFieldSpec

kamy = Kamy()

pdf = kamy.render(
    template="invoice",
    data={...},
    options=RenderOptions(
        format="a4",
        orientation="portrait",
        page_numbers=True,
        pdf_a="2b",  # archival output
        form_fields=[  # fillable AcroForm widgets
            FormFieldSpec(
                name="signature",
                type="signature",
                page=1,
                x=100, y=100,
                width=200, height=40,
            ),
        ],
    ),
)
```

## Error handling

```python
from kamy import Kamy
from kamy import RateLimitError, QuotaExceededError, ValidationError

kamy = Kamy()
try:
    pdf = kamy.render(template="invoice", data={...})
except ValidationError as e:
    print("Bad payload:", e.details)  # {"field.name": ["reason"]}
except RateLimitError as e:
    print(f"Rate limited, retry after {e.retry_after_seconds}s")
except QuotaExceededError:
    print("Monthly quota hit. Upgrade or wait until next billing cycle.")
```

## Documentation

- API reference: <https://kamy.dev/api-reference>
- Docs: <https://kamy.dev/docs>
- OpenAPI spec: <https://kamy.dev/openapi.json>
- TypeScript SDK: <https://www.npmjs.com/package/@kamydev/sdk>
- MCP server: <https://kamy.dev/docs/mcp>

## License

MIT
