Metadata-Version: 2.4
Name: kamy-sdk
Version: 0.6.1
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.")
```

## What's new in 0.6.1

E-signature is now a first-class method. Send any rendered PDF to a
signer and collect a stamped copy:

```python
from kamy import Kamy

kamy = Kamy(api_key="kamy_pk_...")

pdf = kamy.render(template="contract", data={...})

sig = kamy.create_signature(
    render_id=pdf.id,
    signer_email="alice@example.com",
    signer_name="Alice Example",
    # optional — defaults to bottom-right of last page sized 220×64 pt
    position={"page": 3, "x": 360, "y": 80, "w": 220, "h": 64},
    message="Please review and sign by Friday.",
)
print(sig["sign_url"])
print(sig["sign_token"])
```

```python
# List recent requests.
result = kamy.list_signatures(limit=25)
for s in result["signatures"]:
    print(s["id"], s["status"], s["signer_email"])
```

Both methods are mirrored on `AsyncKamy` for asyncio / FastAPI use.
Status flows `pending → signed | voided | expired`; tokens auto-expire
after 30 days.

## What's new in 0.6.0

26 system templates across 10 packs and 5 new endpoints. Every endpoint is
HTTP-callable today — pass `template="<slug>"` plus `data=<dict>` to
`kamy.render()` for any of the new templates.

```python
# MENA
kamy.render(template="bh-vat-invoice",        data={...})  # Bahrain NBR, VAT 10%
kamy.render(template="om-vat-invoice",        data={...})  # Oman OTA, VAT 5%
kamy.render(template="eg-vat-invoice",        data={...})  # Egypt ETA, VAT 14%
kamy.render(template="qa-commercial-invoice", data={...})
kamy.render(template="kw-commercial-invoice", data={...})

# Global compliance
kamy.render(template="uk-vat-invoice",  data={...})  # HMRC
kamy.render(template="eu-vat-invoice",  data={...})  # Directive 2006/112/EC
kamy.render(template="us-w9",           data={...})  # IRS W-9 Rev. Mar 2024
kamy.render(template="us-1099-nec",     data={...})  # IRS 1099-NEC TY 2025
kamy.render(template="in-gst-invoice",  data={...})  # CGST/SGST + IGST
kamy.render(template="au-tax-invoice",  data={...})  # ATO GSTR 2013/1

# UAE verticals + legal
kamy.render(template="uae-tenancy-contract", data={...})
kamy.render(template="uae-noc-letter",       data={...})
kamy.render(template="uae-offer-letter",     data={...})
kamy.render(template="salary-certificate",   data={...})
kamy.render(template="mutual-nda",           data={...})
```

New endpoints (HTTP-callable today; typed methods land in 0.6.x patches):

```bash
POST /v1/render/bulk    # 1 template × N rows → ZIP of N PDFs (cap 25)
POST /v1/render-html    # rendered HTML for email pipelines
POST /v1/render-xlsx    # spec-based XLSX
POST /v1/render-pptx    # spec-based PowerPoint
POST /v1/schedules      # recurring renders on a cron + email/whatsapp/download
```

## 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
