image2ppt 0.1.0__tar.gz

image2ppt-0.1.0/.gitignore

@@ -0,0 +1,27 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# Node / TypeScript
+node_modules/
+typescript/dist/
+*.tsbuildinfo
+npm-debug.log*
+
+# Editors / OS
+.DS_Store
+.idea/
+.vscode/
+
+# Local artifacts
+*.pptx
+out.pptx

image2ppt-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 image2ppt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

image2ppt-0.1.0/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: image2ppt
+Version: 0.1.0
+Summary: Official Python client for the image2ppt API — convert images and PDFs into editable PowerPoint (.pptx).
+Project-URL: Homepage, https://image2ppt.com
+Project-URL: Documentation, https://image2ppt.com/docs/api
+Project-URL: Repository, https://github.com/shrektan/image2ppt-sdk
+Project-URL: Issues, https://github.com/shrektan/image2ppt-sdk/issues
+Author: image2ppt
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,image-to-pptx,image2ppt,ocr,pdf,powerpoint,pptx,presentation,sdk,slides
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+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: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Graphics :: Presentation
+Classifier: Topic :: Office/Business :: Office Suites
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: pillow>=9.0
+Requires-Dist: requests>=2.25
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# image2ppt — Python client
+
+Official Python client for the [image2ppt](https://image2ppt.com) API. Turn a batch of images or PDF pages into one **editable** PowerPoint (`.pptx`).
+
+## Install
+
+```bash
+pip install image2ppt
+```
+
+Requires Python 3.9+. Depends on `requests` and `Pillow` (Pillow powers optional client-side image pre-compression — see below).
+
+## Get an API key
+
+Sign in at [image2ppt.com](https://image2ppt.com), open **Developer / API** from the account menu, and create a key (looks like `i2p_live_xxxx`). It's shown in full **once** — save it. API access is available to accounts with credits.
+
+> **Server-side only.** Keep your key on your backend. Never embed it in a browser, mobile app, or anything a user can inspect.
+
+## Quick start
+
+One shot — submit, wait, download:
+
+```python
+from image2ppt import Image2PPTClient
+
+client = Image2PPTClient(api_key="i2p_live_your_key")
+
+job = client.convert(
+    ["slide1.png", "slide2.png", "report.pdf"],
+    dest_path="out.pptx",
+    locale="zh-CN",       # optional: "zh-CN" (default) or "en"
+    aspect_ratio="16:9",  # optional: "auto" (default) / "16:9" / "4:3"
+)
+print("done — credits used:", job.credits_used, "refunded:", job.credits_refunded)
+```
+
+Step by step, if you want to control polling:
+
+```python
+job = client.submit(["slide1.png"], aspect_ratio="4:3")
+print("job:", job.job_id, "credits reserved:", job.credits_reserved)
+
+job = client.wait(job.job_id, poll_interval=5, timeout=1800)
+client.download(job.job_id, "out.pptx")
+```
+
+Check your balance:
+
+```python
+info = client.account()
+print(info["email"], "credits:", info["credits"])
+```
+
+## How it works
+
+- **Async.** `submit` returns a job id immediately; conversion runs in the background. A single page typically takes ~2 minutes; 90% of jobs finish within 3.
+- **One job = one PPTX.** All files in a submission are merged into a single deck, in upload order.
+- **Billed per page.** 1 page = 1 credit, reserved at submit and settled on completion. If some pages fail but others succeed, the job still `completed`s with the good pages and the failed pages' credits are refunded (`credits_refunded`).
+- **Limits.** Each file ≤ 35MB; total ≤ 50 pages per job (images count as 1, PDFs as their page count).
+- **Client-side pre-compression.** Images are compressed to the server's spec before upload (≤2000px, ≤1MB, JPEG), so the server's own pass is a no-op and you send fewer bytes. PDFs are uploaded as-is and rendered server-side.
+
+## Rate limits
+
+Per account (all keys share the budget): ≤ 10 concurrent jobs, ≤ 60 pages/minute submitted. Over the limit returns `429` with a `Retry-After` hint. `wait()` handles 429 backoff for you automatically. If you call `submit()` directly, catch `RateLimitedError` and honor `retry_after`:
+
+```python
+import time
+from image2ppt import RateLimitedError
+
+while True:
+    try:
+        job = client.submit(paths)
+        break
+    except RateLimitedError as e:
+        time.sleep(e.retry_after or 5)
+```
+
+## Errors
+
+Every exception subclasses `Image2PPTError` and carries `status_code`, `code`, and `message`. Branch on `code`, not `message`.
+
+| Exception | HTTP | code |
+|---|---|---|
+| `AuthenticationError` | 401 / 403 | `INVALID_API_KEY`, `API_KEY_REQUIRED`, `ACCOUNT_DELETED` |
+| `InvalidFileError` | 400 | `INVALID_FILE` |
+| `TooManySlidesError` | 400 | `TOO_MANY_SLIDES` |
+| `InsufficientCreditsError` | 402 | `INSUFFICIENT_CREDITS` |
+| `RateLimitedError` | 429 | `RATE_LIMITED` (has `retry_after`) |
+| `JobNotFoundError` | 404 | `JOB_NOT_FOUND` |
+| `NotReadyError` | 409 | `NOT_READY` |
+| `OutputExpiredError` | 410 | `OUTPUT_EXPIRED` |
+| `JobFailedError` | — | job's `error.code` (raised by `wait()`; `e.job` is the snapshot) |
+| `Image2PPTTimeoutError` | — | — (`wait()` exceeded its `timeout`; job may still be running) |
+
+```python
+from image2ppt import Image2PPTError, JobFailedError
+
+try:
+    job = client.convert(paths, "out.pptx")
+except JobFailedError as e:
+    print("conversion failed:", e.code, e.message)
+except Image2PPTError as e:
+    print("request error:", e.status_code, e.code, e.message)
+```
+
+## Full API reference
+
+See [../docs/api.md](../docs/api.md) for the complete HTTP contract (endpoints, fields, error codes).
+
+## License
+
+[MIT](./LICENSE)

image2ppt-0.1.0/README.md

@@ -0,0 +1,112 @@
+# image2ppt — Python client
+
+Official Python client for the [image2ppt](https://image2ppt.com) API. Turn a batch of images or PDF pages into one **editable** PowerPoint (`.pptx`).
+
+## Install
+
+```bash
+pip install image2ppt
+```
+
+Requires Python 3.9+. Depends on `requests` and `Pillow` (Pillow powers optional client-side image pre-compression — see below).
+
+## Get an API key
+
+Sign in at [image2ppt.com](https://image2ppt.com), open **Developer / API** from the account menu, and create a key (looks like `i2p_live_xxxx`). It's shown in full **once** — save it. API access is available to accounts with credits.
+
+> **Server-side only.** Keep your key on your backend. Never embed it in a browser, mobile app, or anything a user can inspect.
+
+## Quick start
+
+One shot — submit, wait, download:
+
+```python
+from image2ppt import Image2PPTClient
+
+client = Image2PPTClient(api_key="i2p_live_your_key")
+
+job = client.convert(
+    ["slide1.png", "slide2.png", "report.pdf"],
+    dest_path="out.pptx",
+    locale="zh-CN",       # optional: "zh-CN" (default) or "en"
+    aspect_ratio="16:9",  # optional: "auto" (default) / "16:9" / "4:3"
+)
+print("done — credits used:", job.credits_used, "refunded:", job.credits_refunded)
+```
+
+Step by step, if you want to control polling:
+
+```python
+job = client.submit(["slide1.png"], aspect_ratio="4:3")
+print("job:", job.job_id, "credits reserved:", job.credits_reserved)
+
+job = client.wait(job.job_id, poll_interval=5, timeout=1800)
+client.download(job.job_id, "out.pptx")
+```
+
+Check your balance:
+
+```python
+info = client.account()
+print(info["email"], "credits:", info["credits"])
+```
+
+## How it works
+
+- **Async.** `submit` returns a job id immediately; conversion runs in the background. A single page typically takes ~2 minutes; 90% of jobs finish within 3.
+- **One job = one PPTX.** All files in a submission are merged into a single deck, in upload order.
+- **Billed per page.** 1 page = 1 credit, reserved at submit and settled on completion. If some pages fail but others succeed, the job still `completed`s with the good pages and the failed pages' credits are refunded (`credits_refunded`).
+- **Limits.** Each file ≤ 35MB; total ≤ 50 pages per job (images count as 1, PDFs as their page count).
+- **Client-side pre-compression.** Images are compressed to the server's spec before upload (≤2000px, ≤1MB, JPEG), so the server's own pass is a no-op and you send fewer bytes. PDFs are uploaded as-is and rendered server-side.
+
+## Rate limits
+
+Per account (all keys share the budget): ≤ 10 concurrent jobs, ≤ 60 pages/minute submitted. Over the limit returns `429` with a `Retry-After` hint. `wait()` handles 429 backoff for you automatically. If you call `submit()` directly, catch `RateLimitedError` and honor `retry_after`:
+
+```python
+import time
+from image2ppt import RateLimitedError
+
+while True:
+    try:
+        job = client.submit(paths)
+        break
+    except RateLimitedError as e:
+        time.sleep(e.retry_after or 5)
+```
+
+## Errors
+
+Every exception subclasses `Image2PPTError` and carries `status_code`, `code`, and `message`. Branch on `code`, not `message`.
+
+| Exception | HTTP | code |
+|---|---|---|
+| `AuthenticationError` | 401 / 403 | `INVALID_API_KEY`, `API_KEY_REQUIRED`, `ACCOUNT_DELETED` |
+| `InvalidFileError` | 400 | `INVALID_FILE` |
+| `TooManySlidesError` | 400 | `TOO_MANY_SLIDES` |
+| `InsufficientCreditsError` | 402 | `INSUFFICIENT_CREDITS` |
+| `RateLimitedError` | 429 | `RATE_LIMITED` (has `retry_after`) |
+| `JobNotFoundError` | 404 | `JOB_NOT_FOUND` |
+| `NotReadyError` | 409 | `NOT_READY` |
+| `OutputExpiredError` | 410 | `OUTPUT_EXPIRED` |
+| `JobFailedError` | — | job's `error.code` (raised by `wait()`; `e.job` is the snapshot) |
+| `Image2PPTTimeoutError` | — | — (`wait()` exceeded its `timeout`; job may still be running) |
+
+```python
+from image2ppt import Image2PPTError, JobFailedError
+
+try:
+    job = client.convert(paths, "out.pptx")
+except JobFailedError as e:
+    print("conversion failed:", e.code, e.message)
+except Image2PPTError as e:
+    print("request error:", e.status_code, e.code, e.message)
+```
+
+## Full API reference
+
+See [../docs/api.md](../docs/api.md) for the complete HTTP contract (endpoints, fields, error codes).
+
+## License
+
+[MIT](./LICENSE)

image2ppt-0.1.0/pyproject.toml

@@ -0,0 +1,62 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "image2ppt"
+version = "0.1.0"
+description = "Official Python client for the image2ppt API — convert images and PDFs into editable PowerPoint (.pptx)."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "image2ppt" }]
+keywords = [
+    "image2ppt",
+    "pptx",
+    "powerpoint",
+    "presentation",
+    "slides",
+    "pdf",
+    "ocr",
+    "image-to-pptx",
+    "api",
+    "sdk",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Office/Business :: Office Suites",
+    "Topic :: Multimedia :: Graphics :: Presentation",
+    "Typing :: Typed",
+]
+dependencies = [
+    "requests>=2.25",
+    "Pillow>=9.0",
+]
+
+[project.urls]
+Homepage = "https://image2ppt.com"
+Documentation = "https://image2ppt.com/docs/api"
+Repository = "https://github.com/shrektan/image2ppt-sdk"
+Issues = "https://github.com/shrektan/image2ppt-sdk/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=7"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/image2ppt"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "README.md", "LICENSE"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

image2ppt-0.1.0/src/image2ppt/__init__.py

@@ -0,0 +1,50 @@
+"""Official Python client for the image2ppt API.
+
+Convert images and PDFs into editable PowerPoint (.pptx) decks.
+
+    from image2ppt import Image2PPTClient
+
+    client = Image2PPTClient(api_key="i2p_live_...")
+    job = client.convert(["slide1.png", "report.pdf"], dest_path="out.pptx")
+    print("credits used:", job.credits_used)
+
+See https://github.com/shrektan/image2ppt-sdk for docs and examples.
+"""
+
+from __future__ import annotations
+
+from .client import DEFAULT_BASE_URL, Image2PPTClient
+from .errors import (
+    AuthenticationError,
+    Image2PPTError,
+    Image2PPTTimeoutError,
+    InsufficientCreditsError,
+    InvalidFileError,
+    JobFailedError,
+    JobNotFoundError,
+    NotReadyError,
+    OutputExpiredError,
+    RateLimitedError,
+    TooManySlidesError,
+)
+from .models import Job
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Image2PPTClient",
+    "Job",
+    "DEFAULT_BASE_URL",
+    "Image2PPTError",
+    "AuthenticationError",
+    "InvalidFileError",
+    "TooManySlidesError",
+    "InsufficientCreditsError",
+    "RateLimitedError",
+    "JobNotFoundError",
+    "NotReadyError",
+    "OutputExpiredError",
+    "JobFailedError",
+    "Image2PPTTimeoutError",
+    "__version__",
+]

image2ppt-0.1.0/src/image2ppt/_compress.py

@@ -0,0 +1,72 @@
+"""Client-side image compression, matched to the server's upload pipeline.
+
+The server runs the same compression on every upload (``compressImageForUpload``).
+By pre-compressing to the same spec, the server's pass becomes a passthrough — one
+less redundant compute, fewer bytes on the wire. These constants must stay in sync
+with the server; changing one means changing both.
+"""
+
+from __future__ import annotations
+
+import io
+
+from PIL import Image
+
+_UPLOAD_TARGET_BYTES = 1024 * 1024
+_UPLOAD_MAX_DIM = 2000
+_UPLOAD_QUALITY_LADDER = (90, 85, 80)
+# Only PNG / JPEG pass through as-is; WebP / GIF are transcoded to JPEG even when
+# small (matching the server, which transcodes anything that isn't PNG/JPEG first).
+_PASSTHROUGH_MIMES = frozenset({"image/png", "image/jpeg"})
+IMAGE_MIMES = frozenset({"image/png", "image/jpeg", "image/webp", "image/gif"})
+
+
+def compress_image_for_upload(raw: bytes, mime: str) -> "tuple[bytes, str]":
+    """Compress an image to the server's spec; return ``(bytes, mime)``.
+
+    Rules mirror the server's ``compressImageForUpload``:
+      - PNG/JPEG with longest edge <= 2000px and <= 1MB -> returned as-is (passthrough).
+      - Otherwise: fit inside 2000x2000 (shrink only), flatten transparency onto
+        white, JPEG at quality 90 -> 85 -> 80 until <= 1MB or the ladder bottoms out.
+      - Fallback: if compression somehow yields a larger file (already-low-quality
+        sources do this) -> return the original, never "blurrier AND bigger".
+
+    Only images go through here; PDFs are uploaded as-is and rendered server-side.
+    """
+    with Image.open(io.BytesIO(raw)) as img:
+        img.load()  # animated GIF / WebP: first frame only (Pillow default)
+        width, height = img.size
+        within_budget = (
+            len(raw) <= _UPLOAD_TARGET_BYTES and max(width, height) <= _UPLOAD_MAX_DIM
+        )
+        if within_budget and mime in _PASSTHROUGH_MIMES:
+            return raw, mime
+
+        scaled = img.copy()
+        # thumbnail = fit inside, no enlargement (server's fit:inside + withoutEnlargement).
+        if max(width, height) > _UPLOAD_MAX_DIM:
+            scaled.thumbnail((_UPLOAD_MAX_DIM, _UPLOAD_MAX_DIM), Image.LANCZOS)
+
+        # Flatten onto white, dropping alpha (server's .flatten({background:'#ffffff'})).
+        has_alpha = scaled.mode in ("RGBA", "LA") or (
+            scaled.mode == "P" and "transparency" in scaled.info
+        )
+        if has_alpha:
+            rgba = scaled.convert("RGBA")
+            flattened = Image.new("RGB", rgba.size, (255, 255, 255))
+            flattened.paste(rgba, mask=rgba.split()[-1])
+            scaled = flattened
+        else:
+            scaled = scaled.convert("RGB")
+
+        compressed = None
+        for quality in _UPLOAD_QUALITY_LADDER:
+            buffer = io.BytesIO()
+            scaled.save(buffer, format="JPEG", quality=quality)
+            compressed = buffer.getvalue()
+            if len(compressed) <= _UPLOAD_TARGET_BYTES:
+                break
+
+    if compressed is None or len(compressed) >= len(raw):
+        return raw, mime
+    return compressed, "image/jpeg"

image2ppt-0.1.0/src/image2ppt/client.py

@@ -0,0 +1,280 @@
+"""The image2ppt API client."""
+
+from __future__ import annotations
+
+import mimetypes
+import os
+import time
+from typing import Any, Dict, Optional, Sequence
+
+import requests
+
+from ._compress import IMAGE_MIMES, compress_image_for_upload
+from .errors import (
+    Image2PPTError,
+    Image2PPTTimeoutError,
+    JobFailedError,
+    RateLimitedError,
+    exception_for,
+)
+from .models import Job
+
+DEFAULT_BASE_URL = "https://image2ppt.com"
+
+
+class Image2PPTClient:
+    """Client for the image2ppt API.
+
+    Args:
+        api_key: Your API key (looks like ``i2p_live_...``), created on the
+            Developer / API page.
+        base_url: Service base URL, defaults to ``https://image2ppt.com``.
+        timeout: Per-HTTP-request timeout in seconds (not the whole-job wait).
+        session: Optional ``requests.Session`` to inject (for testing or pooling).
+    """
+
+    #: Supported input extensions -> MIME type (for labeling multipart uploads).
+    _MIME_BY_EXT = {
+        ".png": "image/png",
+        ".jpg": "image/jpeg",
+        ".jpeg": "image/jpeg",
+        ".webp": "image/webp",
+        ".gif": "image/gif",
+        ".pdf": "application/pdf",
+    }
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        *,
+        timeout: float = 60.0,
+        session: Optional[requests.Session] = None,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key must not be empty")
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self._session = session or requests.Session()
+        self._session.headers.update({"Authorization": f"Bearer {api_key}"})
+
+    # ----- public methods ---------------------------------------------- #
+    def submit(
+        self,
+        paths: Sequence[str],
+        *,
+        locale: Optional[str] = None,
+        aspect_ratio: Optional[str] = None,
+    ) -> Job:
+        """Submit a batch of files and create a conversion job.
+
+        Args:
+            paths: Local file paths (one or more). Supports png/jpeg/webp/gif/pdf,
+                each file <= 35MB. An image is 1 page, a PDF is its page count;
+                the total must be <= 50 pages.
+            locale: ``zh-CN`` (default) or ``en``.
+            aspect_ratio: ``auto`` (default) / ``16:9`` / ``4:3``.
+
+        Returns:
+            A ``Job`` with ``status`` ``pending``, plus ``slide_count`` and
+            ``credits_reserved`` (credits locked at submit time).
+
+        Raises:
+            AuthenticationError, InvalidFileError, TooManySlidesError,
+            InsufficientCreditsError, RateLimitedError.
+        """
+        paths = list(paths)
+        if not paths:
+            raise ValueError("at least one file is required")
+
+        data: Dict[str, str] = {}
+        if locale is not None:
+            data["locale"] = locale
+        if aspect_ratio is not None:
+            data["aspectRatio"] = aspect_ratio
+
+        opened = []
+        multipart = []
+        try:
+            for path in paths:
+                filename = os.path.basename(path)
+                mime = self._guess_mime(filename)
+                if mime in IMAGE_MIMES:
+                    # Images: pre-compress to the server spec so its pass is a passthrough.
+                    with open(path, "rb") as fh:
+                        raw = fh.read()
+                    payload, out_mime = compress_image_for_upload(raw, mime)
+                    if out_mime == "image/jpeg" and not filename.lower().endswith(
+                        (".jpg", ".jpeg")
+                    ):
+                        # Compressed to JPEG: align the extension so name matches content.
+                        filename = os.path.splitext(filename)[0] + ".jpg"
+                    multipart.append(("files", (filename, payload, out_mime)))
+                else:
+                    # PDFs and other non-images: upload as-is (streamed), render server-side.
+                    handle = open(path, "rb")
+                    opened.append(handle)
+                    multipart.append(("files", (filename, handle, mime)))
+            resp = self._session.post(
+                f"{self.base_url}/api/v1/jobs",
+                files=multipart,
+                data=data,
+                timeout=self.timeout,
+            )
+        finally:
+            for handle in opened:
+                handle.close()
+
+        return Job.from_dict(self._parse_json(resp))
+
+    def get_job(self, job_id: str) -> Job:
+        """Fetch the current job state as a ``Job`` snapshot. Raises JobNotFoundError."""
+        resp = self._session.get(
+            f"{self.base_url}/api/v1/jobs/{job_id}",
+            timeout=self.timeout,
+        )
+        return Job.from_dict(self._parse_json(resp))
+
+    def wait(
+        self,
+        job_id: str,
+        *,
+        poll_interval: float = 5.0,
+        timeout: float = 1800.0,
+    ) -> Job:
+        """Poll until the job reaches a terminal state; return the completed ``Job``.
+
+        The poll interval starts at ``poll_interval`` and backs off to 15s max. On a
+        429 it waits the ``Retry-After`` seconds before continuing. A failed job
+        raises JobFailedError; exceeding ``timeout`` raises Image2PPTTimeoutError
+        (the job itself may still be running).
+
+        Args:
+            job_id: The job id.
+            poll_interval: Initial poll interval in seconds (default 5).
+            timeout: Overall wait cap in seconds (default 1800 = 30 min).
+        """
+        deadline = time.monotonic() + timeout
+        interval = poll_interval
+        while True:
+            try:
+                job = self.get_job(job_id)
+            except RateLimitedError as exc:
+                sleep_for = exc.retry_after if exc.retry_after is not None else interval
+                self._sleep_until(deadline, sleep_for, job_id)
+                continue
+
+            if job.is_completed:
+                return job
+            if job.is_failed:
+                err = job.error or {}
+                raise JobFailedError(
+                    err.get("message") or "conversion failed",
+                    code=err.get("code"),
+                    job=job,
+                )
+
+            self._sleep_until(deadline, interval, job_id)
+            interval = min(interval * 1.5, 15.0)
+
+    def download(self, job_id: str, dest_path: str) -> str:
+        """Stream a completed job's PPTX to ``dest_path``; return that path.
+
+        Raises NotReadyError (409) if the job isn't done, JobNotFoundError (404) if
+        it doesn't exist, OutputExpiredError (410) if the deliverable was reaped.
+        """
+        resp = self._session.get(
+            f"{self.base_url}/api/v1/jobs/{job_id}/download",
+            stream=True,
+            timeout=self.timeout,
+        )
+        try:
+            if not resp.ok:
+                self._raise_for_error(resp)
+            with open(dest_path, "wb") as out:
+                for chunk in resp.iter_content(chunk_size=65536):
+                    if chunk:
+                        out.write(chunk)
+        finally:
+            resp.close()
+        return dest_path
+
+    def convert(
+        self,
+        paths: Sequence[str],
+        dest_path: str,
+        *,
+        locale: Optional[str] = None,
+        aspect_ratio: Optional[str] = None,
+        poll_interval: float = 5.0,
+        timeout: float = 1800.0,
+    ) -> Job:
+        """One-shot: submit -> wait for completion -> download to ``dest_path``.
+
+        Arguments mirror ``submit`` and ``wait``. For the synchronous
+        "give me a batch of images, hand me back a PPTX" case.
+        """
+        job = self.submit(paths, locale=locale, aspect_ratio=aspect_ratio)
+        completed = self.wait(job.job_id, poll_interval=poll_interval, timeout=timeout)
+        self.download(completed.job_id, dest_path)
+        return completed
+
+    def account(self) -> Dict[str, Any]:
+        """Return account info: ``{"email": ..., "credits": available_credits}``."""
+        resp = self._session.get(
+            f"{self.base_url}/api/v1/account",
+            timeout=self.timeout,
+        )
+        return self._parse_json(resp)
+
+    # ----- internal helpers -------------------------------------------- #
+    def _guess_mime(self, filename: str) -> str:
+        ext = os.path.splitext(filename)[1].lower()
+        if ext in self._MIME_BY_EXT:
+            return self._MIME_BY_EXT[ext]
+        guessed, _ = mimetypes.guess_type(filename)
+        return guessed or "application/octet-stream"
+
+    def _sleep_until(self, deadline: float, seconds: float, job_id: str) -> None:
+        """Sleep ``seconds``, but never past ``deadline``; raise TimeoutError if past."""
+        remaining = deadline - time.monotonic()
+        if remaining <= 0:
+            raise Image2PPTTimeoutError(f"timed out waiting for job {job_id}", job_id=job_id)
+        time.sleep(min(seconds, remaining))
+
+    def _parse_json(self, resp: requests.Response) -> Dict[str, Any]:
+        """Return the JSON body on 2xx; otherwise raise the mapped exception."""
+        if not resp.ok:
+            self._raise_for_error(resp)
+        return resp.json()
+
+    def _raise_for_error(self, resp: requests.Response) -> None:
+        """Parse the ``{"error": {code, message}}`` envelope and raise the mapped error."""
+        code: Optional[str] = None
+        message: Optional[str] = None
+        try:
+            body = resp.json()
+            err = body.get("error") if isinstance(body, dict) else None
+            if isinstance(err, dict):
+                code = err.get("code")
+                message = err.get("message")
+        except ValueError:
+            pass  # non-JSON error body (e.g. a gateway HTML page): fall back to status text
+        message = message or f"request failed (HTTP {resp.status_code})"
+
+        raise exception_for(
+            status_code=resp.status_code,
+            code=code,
+            message=message,
+            retry_after=self._parse_retry_after(resp.headers.get("Retry-After")),
+        )
+
+    @staticmethod
+    def _parse_retry_after(value: Optional[str]) -> Optional[float]:
+        """Parse the Retry-After header as seconds (contract: integer seconds)."""
+        if not value:
+            return None
+        try:
+            return float(value)
+        except (TypeError, ValueError):
+            return None

image2ppt-0.1.0/src/image2ppt/errors.py

@@ -0,0 +1,155 @@
+"""Exception hierarchy for the image2ppt client.
+
+Every error carries the HTTP ``status_code``, the server error ``code`` (from the
+``{"error": {"code", "message"}}`` envelope), and a human-readable ``message``.
+Branch on ``code``, not ``message`` — messages may be reworded.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+
+class Image2PPTError(Exception):
+    """Base class for all client errors."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: Optional[int] = None,
+        code: Optional[str] = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.code = code
+
+    def __str__(self) -> str:
+        parts = []
+        if self.status_code is not None:
+            parts.append(f"HTTP {self.status_code}")
+        if self.code:
+            parts.append(self.code)
+        prefix = " ".join(parts)
+        return f"[{prefix}] {self.message}" if prefix else self.message
+
+
+class AuthenticationError(Image2PPTError):
+    """API key is missing, invalid, or the account is gone (401 / 403)."""
+
+
+class InvalidFileError(Image2PPTError):
+    """A file was rejected: unsupported format or over the 35MB per-file limit (400)."""
+
+
+class TooManySlidesError(Image2PPTError):
+    """The submission exceeds the 50-page-per-job limit (400 TOO_MANY_SLIDES)."""
+
+
+class InsufficientCreditsError(Image2PPTError):
+    """Not enough available credits to cover the submission (402)."""
+
+
+class RateLimitedError(Image2PPTError):
+    """Rate limited (429 RATE_LIMITED).
+
+    ``retry_after`` is the server-suggested wait in seconds (from the
+    ``Retry-After`` header); retry after that long.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: Optional[int] = None,
+        code: Optional[str] = None,
+        retry_after: Optional[float] = None,
+    ) -> None:
+        super().__init__(message, status_code=status_code, code=code)
+        self.retry_after = retry_after
+
+
+class JobNotFoundError(Image2PPTError):
+    """The job id doesn't exist, or isn't owned by this key's account (404)."""
+
+
+class NotReadyError(Image2PPTError):
+    """The job hasn't finished yet, so the deliverable can't be downloaded (409)."""
+
+
+class OutputExpiredError(Image2PPTError):
+    """The job finished, but its PPTX passed the retention window and was reaped (410)."""
+
+
+class JobFailedError(Image2PPTError):
+    """The job ended in failure (raised by ``wait`` when it polls status=failed).
+
+    ``job`` is the failure snapshot; ``code`` / ``message`` come from its ``error`` field.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: Optional[str] = None,
+        job: Optional[Any] = None,
+    ) -> None:
+        super().__init__(message, code=code)
+        self.job = job
+
+
+class Image2PPTTimeoutError(Image2PPTError):
+    """``wait`` exceeded its ``timeout`` before the job reached a terminal state.
+
+    This does not mean the job failed — it may still be running. Re-``wait`` on the
+    ``job_id`` later. (The prefix avoids shadowing the builtin ``TimeoutError``.)
+    """
+
+    def __init__(self, message: str, *, job_id: Optional[str] = None) -> None:
+        super().__init__(message)
+        self.job_id = job_id
+
+
+# Server error code -> exception class. Unlisted codes fall back to the status-code
+# map, then to the base class.
+_CODE_TO_EXC: Dict[str, type] = {
+    "INVALID_API_KEY": AuthenticationError,
+    "API_KEY_REQUIRED": AuthenticationError,
+    "ACCOUNT_DELETED": AuthenticationError,
+    "INVALID_FILE": InvalidFileError,
+    "INVALID_PDF": InvalidFileError,
+    "TOO_MANY_SLIDES": TooManySlidesError,
+    "INSUFFICIENT_CREDITS": InsufficientCreditsError,
+    "RATE_LIMITED": RateLimitedError,
+    "JOB_NOT_FOUND": JobNotFoundError,
+    "NOT_READY": NotReadyError,
+    "OUTPUT_EXPIRED": OutputExpiredError,
+}
+_STATUS_TO_EXC: Dict[int, type] = {
+    401: AuthenticationError,
+    402: InsufficientCreditsError,
+    404: JobNotFoundError,
+    409: NotReadyError,
+    410: OutputExpiredError,
+    429: RateLimitedError,
+}
+
+
+def exception_for(
+    *,
+    status_code: int,
+    code: Optional[str],
+    message: str,
+    retry_after: Optional[float] = None,
+) -> Image2PPTError:
+    """Build the mapped exception for an error envelope."""
+    if status_code == 429:
+        return RateLimitedError(
+            message,
+            status_code=429,
+            code=code or "RATE_LIMITED",
+            retry_after=retry_after,
+        )
+    exc_cls = _CODE_TO_EXC.get(code or "") or _STATUS_TO_EXC.get(status_code, Image2PPTError)
+    return exc_cls(message, status_code=status_code, code=code)

image2ppt-0.1.0/src/image2ppt/models.py

@@ -0,0 +1,62 @@
+"""Data models returned by the client."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, Optional
+
+
+@dataclass
+class Job:
+    """A snapshot of a conversion job's state.
+
+    Which fields are populated depends on the source: a ``submit`` response only
+    carries ``credits_reserved``; a ``get_job`` response carries
+    ``credits_used`` / ``credits_refunded`` / ``download_url`` and friends.
+    """
+
+    job_id: str
+    status: str  # pending | processing | completed | failed
+    slide_count: Optional[int] = None
+    progress: Optional[int] = None  # 0-100
+    credits_reserved: Optional[int] = None  # submit response: credits locked
+    credits_used: Optional[int] = None  # settled: credits actually charged
+    credits_refunded: Optional[int] = None  # partial success: refunded failed pages
+    created_at: Optional[str] = None
+    completed_at: Optional[str] = None
+    download_url: Optional[str] = None  # completed only; relative path
+    error: Optional[Dict[str, Any]] = None  # failed only; {code, message}
+    raw: Optional[Dict[str, Any]] = None  # raw response body, for forward-compat fields
+
+    @property
+    def is_completed(self) -> bool:
+        """Whether the job finished successfully (deliverable downloadable)."""
+        return self.status == "completed"
+
+    @property
+    def is_failed(self) -> bool:
+        """Whether the job failed."""
+        return self.status == "failed"
+
+    @property
+    def is_terminal(self) -> bool:
+        """Whether the job reached a terminal state (completed or failed)."""
+        return self.status in ("completed", "failed")
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Job":
+        """Build a Job from server JSON; handles both submit and status shapes."""
+        return cls(
+            job_id=data["jobId"],
+            status=data["status"],
+            slide_count=data.get("slideCount"),
+            progress=data.get("progress"),
+            credits_reserved=data.get("creditsReserved"),
+            credits_used=data.get("creditsUsed"),
+            credits_refunded=data.get("creditsRefunded"),
+            created_at=data.get("createdAt"),
+            completed_at=data.get("completedAt"),
+            download_url=data.get("downloadUrl"),
+            error=data.get("error"),
+            raw=data,
+        )