imazeo 1.0.0__tar.gz

imazeo-1.0.0/.gitignore

@@ -0,0 +1,16 @@
+node_modules/
+dist/
+*.tgz
+.DS_Store
+coverage/
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.venv/
+venv/
+build/
+*.whl

imazeo-1.0.0/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+## 1.0.0
+
+### Added
+
+- Initial official Python SDK (`imazeo`)
+- Resources: `context`, `images`, `transforms`, `qr`, `barcodes`, `pdf`
+- Typed errors mapped from Imazeo API envelopes
+- API version allowlist (`v1`) separate from SDK SemVer
+- Multipart uploads with required `X-Upload-Length`
+- Binary response helpers for images/PDF/QR/barcode
+- Image list `q` filename-prefix filter
+- Transform download `If-None-Match` → HTTP 304 as `BinaryResult.not_modified`
+- Default HTTP transport refuses redirects so `X-API-Key` stays on the configured origin
+- Reviewed API-key-only OpenAPI snapshot bundled as `openapi/backend.json`
+- Native CI verification and independent SemVer/tag checks
+
+### Media contract
+
+- Barcode: required `type` and `content`; optional `format` (`png`/`svg`) and `includeText`
+- PDF merge uses repeated multipart `file` parts in order
+- Integer model types for barcode scale and image hue where applicable
+
+### Deferred (API-key routes exist; not in SDK_BEHAVIOR §1)
+
+- Tool artifacts CRUD/download
+- Project outputs list
+
+### API compatibility
+
+- Default API: `v1`
+- Supported API versions: `v1`
+- Default base URL: `https://api.imazeo.com`

imazeo-1.0.0/GUIDE.md

@@ -0,0 +1,141 @@
+# Imazeo Python integration guide
+
+## 1. Prepare a server integration
+
+Install the package:
+
+```bash
+pip install imazeo
+```
+
+Package: [`imazeo`](https://pypi.org/project/imazeo/) on PyPI.
+Source: [manishbalodia/imazeo-python](https://github.com/manishbalodia/imazeo-python).
+Use the package README for runtime details.
+
+Create a Customer account, complete required verification, create a project and
+issue a project key. Set IMAZEO_API_KEY in protected server configuration and
+IMAZEO_API_ORIGIN to the supplied API origin (no /v1 suffix; production default
+`https://api.imazeo.com`). Use HTTPS outside loopback development. A key can
+resolve its project through GET /v1/api-key/context; that response has projectId
+and keyId, not plan limits or the secret key.
+
+The Main site's documentation paths, served by your configured Main origin, are:
+/docs/getting-started/, /docs/authentication/ and /docs/projects/.
+These paths are site-relative; this guide does not assume a live production domain.
+
+## 2. Generate a QR code and render a delivery note
+
+The following example uses the `imazeo` package. Obtain the original two-page synthetic
+delivery-note.pdf from the Main site's /examples/assets/delivery-note.pdf and put it
+in the working directory. The event URL is fictional. Run only against your configured
+API deployment with the required entitlements and credits.
+
+```python
+import os
+import base64
+from pathlib import Path
+from imazeo import Imazeo, PdfMultiPageResult
+
+# Context manager closes the underlying HTTP client.
+with Imazeo(api_key=os.environ['IMAZEO_API_KEY'],
+            base_url=os.environ['IMAZEO_API_ORIGIN']) as client:
+    qr = client.qr.generate({
+        'content': 'https://example.com/events/studio-open-day',
+        'format': 'svg', 'size': 384,
+    })
+    Path('event-check-in.svg').write_bytes(qr.data)
+    result = client.pdf.render(Path('delivery-note.pdf').read_bytes(), {
+        'pages': '1,2', 'format': 'png',
+    })
+    if isinstance(result, PdfMultiPageResult):
+        for page in result.pages:
+            Path(f"delivery-page-{page['pageNumber']}.png").write_bytes(
+                base64.b64decode(page['data'], validate=True))
+    else:
+        Path('delivery-page.png').write_bytes(result.data)
+```
+
+All six SDK default transports refuse HTTP redirects so project credentials stay
+on the configured API origin. The examples also set safe redirect policies where
+custom client hooks are used. Custom fetch functions, Java HttpClient instances,
+.NET HttpClient/message handlers and Python/PHP handlers must preserve this rule.
+Never forward project credentials to a redirected host.
+
+QR success is binary SVG. A one-page PDF render returns binary image bytes; multiple
+selected pages return base64 page data. This SDK's render result is:
+BinaryResult or PdfMultiPageResult. Decode base64 exactly once; use each page's contentType if you
+change the selected format. The example uses PNG and .png filenames deliberately.
+
+## 3. Upload and transform images
+
+Use the image upload method with file bytes and explicit filename/content type
+as documented in the README. It sends multipart field file and the exact
+X-Upload-Length file byte count. Filenames are metadata, not paths or resource IDs.
+Keep the returned image ID, then create a transform with imageId and transform.
+REST uses _id; use the native ID accessor shown in the README.
+
+CACHE and PERSIST retain derivatives according to their mode rules. EPHEMERAL
+only returns immediate bytes. All transform success bodies are binary. Image
+originals preserve original metadata; generated derivatives strip metadata.
+The HTTP guides are /docs/images/, /docs/transforms/ and /docs/quickstart/.
+
+## 4. Choose PDF and code inputs
+
+PDF info returns parsed JSON and costs one credit. Render costs one per selected
+page; merge costs two; extract costs one. Page numbers are one-based. Select
+pages, a complete rangeStart/rangeEnd pair, or render-only all=true; do not combine
+selectors. Render defaults to page 1; extract requires an explicit selection.
+Merge upload order determines document order. Encrypted/invalid PDFs are rejected.
+
+QR and barcode generation each cost one credit and return PNG or SVG. Barcode
+content must be a string, including numeric identifiers with leading zeros.
+Send numbers and booleans as native values, and omit unused optional fields instead
+of null. A barcode renderer does not assign registered retail identifiers; QR
+generation does not provide dynamic redirect hosting.
+Detailed guides: /docs/pdf/, /docs/qr/, /docs/barcodes/ and /docs/workflows/.
+
+## 5. Handle pagination, downloads and errors
+
+Image/transform lists return a Page wrapper with items and page/limit/total/pages.
+Pagination is explicit; clients do not silently fetch all pages. Only image lists
+accept q as a filename-prefix filter; transformation lists accept page and limit.
+This is not unrestricted full-text search.
+Binary results contain bytes, content type, headers and request ID. Derivative
+downloads support conditional ETags. A not-modified result has no new bytes:
+retain your cached file instead of replacing it with an empty body.
+
+SDK errors expose status, code, request ID and details using native language names
+listed in the README. Network errors do not guarantee an HTTP status. Log only
+sanitized diagnostics; never log a key, source media or base64 PDF pages. Fix
+validation/authentication/entitlement failures. For temporary 429 or busy responses,
+use bounded backoff only when replay is safe and honor Retry-After if supplied.
+No general idempotency-key mechanism is promised. A timed-out mutation may already
+have completed; reconcile known IDs/state before repeating it. SDKs do not
+automatically retry mutations.
+See /docs/errors/ and /docs/troubleshooting/.
+
+## 6. Retain outputs and operate in production
+
+PDF/code output is transient unless you retain the bytes or separately save a
+private artifact through HTTP. Saved artifacts, unified output inventory, usage,
+account/project/key management and Admin APIs are outside the SDK's core media
+scope. Use Customer Bearer authentication for management, not a project key.
+Do not combine Bearer and X-API-Key in one request.
+
+There is no public CDN or customer signed-delivery URL in this contract. Deliver
+bytes through your own authorized server. Never bundle a project key into browser,
+mobile or end-user applications. Your server must enforce its own per-user access.
+
+Bound source sizes, output bytes, page counts and concurrency: these SDKs buffer
+media and base64 pages require extra memory. Default client timeouts are 30 seconds
+for light operations, 60 seconds for images and 120 seconds for PDFs; they do not
+extend backend worker deadlines. Check assigned account limits, not just public
+pricing templates. Cache hits still consume output bandwidth; an authenticated
+derivative 304 consumes no output bandwidth. Deletion refunds storage, not past
+credits/bandwidth. Expiry and physical cleanup are separate.
+
+Production and reference paths: /docs/outputs/, /docs/limits/, /docs/security/,
+/docs/production/ and /docs/api-reference/. The developer OpenAPI download is
+/openapi/imazeo-developer.json. It is a curated development snapshot and excludes
+Admin/account operations and the known defective unified Outputs list; use
+resource-specific lists to enumerate inventory.

imazeo-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Imazeo
+
+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.

imazeo-1.0.0/PKG-INFO

@@ -0,0 +1,210 @@
+Metadata-Version: 2.5
+Name: imazeo
+Version: 1.0.0
+Summary: Official Imazeo Python SDK for server-side image, transform, PDF, QR, and barcode APIs
+Project-URL: Homepage, https://pypi.org/project/imazeo/
+Project-URL: Documentation, https://github.com/manishbalodia/imazeo-python#readme
+Project-URL: Repository, https://github.com/manishbalodia/imazeo-python
+Project-URL: Issues, https://github.com/manishbalodia/imazeo-python/issues
+Author: Imazeo
+License-Expression: MIT
+License-File: LICENSE
+Keywords: barcode,images,imazeo,pdf,qr,sdk,transforms
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# imazeo
+
+Official **server-side** Python SDK for Imazeo.
+
+|                |                                 |
+| -------------- | ------------------------------- |
+| Package        | `imazeo`                        |
+| SDK version    | `1.0.0`                         |
+| Default API    | `v1`                            |
+| Supported APIs | `v1`                            |
+| Runtime        | Python **3.10+** (sync `httpx`) |
+| Registry       | [PyPI](https://pypi.org/project/imazeo/) |
+| Source         | [GitHub](https://github.com/manishbalodia/imazeo-python) |
+
+> **Security:** Secret API keys (`X-API-Key`) are for trusted servers only.
+> Do **not** ship this client with a secret key in browsers or client apps.
+
+Integration contract and learning path: [GUIDE.md](GUIDE.md).
+
+## Install
+
+```bash
+pip install imazeo
+```
+
+Requires Python 3.10+. Create a project API key in the Imazeo customer portal.
+Default API origin is `https://api.imazeo.com` (override with `base_url` when needed).
+
+## Learning path
+
+Read the self-contained [integration guide](GUIDE.md) for project/key setup,
+language examples, PDF response types, pagination, output retention, troubleshooting
+and production practices.
+
+The default HTTP client refuses redirects so credentials stay on the configured
+API origin.
+
+## Quick start
+
+```python
+from pathlib import Path
+from imazeo import Imazeo
+import os
+
+client = Imazeo(
+    api_key=os.environ["IMAZEO_API_KEY"],
+    base_url=os.environ["IMAZEO_API_ORIGIN"],  # supplied API origin
+    # project_id="…",  # optional; otherwise resolved via /v1/api-key/context
+)
+
+qr = client.qr.generate({
+    "content": "https://imazeo.com",
+    "format": "png",
+    "size": 256,
+})
+Path("qr.png").write_bytes(qr.data)
+client.close()
+```
+
+Or use as a context manager:
+
+```python
+with Imazeo(api_key=os.environ["IMAZEO_API_KEY"]) as client:
+    ctx = client.context.get()
+    print(ctx["projectId"], ctx["keyId"])
+```
+
+## Authentication
+
+```python
+Imazeo(api_key=os.environ["IMAZEO_API_KEY"])
+```
+
+Sends `X-API-Key` only. Never send `Authorization` together with an API key
+(backend rejects that combination).
+
+## Resources
+
+| Resource            | Methods                                                                          |
+| ------------------- | -------------------------------------------------------------------------------- |
+| `client.context`    | `get()` → project/key IDs                                                        |
+| `client.images`     | `upload`, `list` (`page`/`limit`/`q`), `get`, `delete`, `download`               |
+| `client.transforms` | `create`, `list`, `get`, `download` (`if_none_match` → `not_modified`), `delete` |
+| `client.qr`         | `generate`                                                                       |
+| `client.barcodes`   | `generate`                                                                       |
+| `client.pdf`        | `info`, `render`, `merge`, `extract`                                             |
+
+### Upload + transform
+
+```python
+image = client.images.upload(
+    photo_bytes,
+    filename="photo.jpg",
+    content_type="image/jpeg",
+)
+
+out = client.transforms.create({
+    "imageId": image["_id"],
+    "mode": "EPHEMERAL",
+    "transform": {"width": 1200, "format": "webp", "quality": 85},
+})
+# out.data → bytes
+```
+
+### Remote URL transform
+
+```python
+out = client.transforms.create({
+    "url": "https://example.com/image.jpg",
+    "transform": {"width": 640, "format": "jpeg"},
+})
+```
+
+### PDF
+
+```python
+info = client.pdf.info(pdf_bytes)
+page = client.pdf.render(pdf_bytes, {"pages": "1", "format": "png"})
+merged = client.pdf.merge([pdf_a, pdf_b])
+extracted = client.pdf.extract(pdf_bytes, {"pages": "1,2"})
+```
+
+## Errors
+
+```python
+from imazeo import ImazeoError, RateLimitError
+
+try:
+    client.images.get(image_id)
+except RateLimitError as error:
+    print(error.code, error.request_id)
+except ImazeoError as error:
+    print(error.status, error.code, error.message)
+```
+
+## Configuration
+
+| Option        | Default                  | Notes                                  |
+| ------------- | ------------------------ | -------------------------------------- |
+| `api_key`     | required                 | Secret key                             |
+| `project_id`  | from context             | Path project                           |
+| `base_url`    | `https://api.imazeo.com` | Origin only; `/v1` stripped if present |
+| `api_version` | `v1`                     | Allowlisted                            |
+| `timeout_ms`  | `60000`                  | PDF uses 120s; QR/barcode 30s          |
+| `app_name`    | —                        | Appended to User-Agent                 |
+| `transport`   | —                        | Optional `httpx.BaseTransport` (tests) |
+
+## API version vs package version
+
+- **API** path version: `v1` (configured via `api_version`)
+- **SDK** SemVer: `1.0.0`
+
+`Imazeo.api_compatibility()` reports supported API versions.
+
+## Not included
+
+Portal JWT APIs (projects CRUD, API-key management, usage, plans, tickets, auth),
+admin APIs, tool-artifacts, outputs, and browser secret-key usage.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT
+
+## Media contract update — 2026-10-02
+
+Barcode generation requires `type` and string `content`; optional `format` is
+`png` or `svg` (default `png`), and `includeText` is a boolean (default `true`).
+The old `data`, `output` and `includetext` fields are removed before release.
+PDF merge sends repeated `file` parts in order. Omit optional fields for defaults;
+JSON numbers/booleans are not coerced and top-level optional nulls are rejected.
+Barcode scale and image hue are integers. Methods retain language-specific names.
+The reviewed API-key-only contract is bundled in `openapi/backend.json`.
+
+```python
+client.barcodes.generate({'type': 'code128', 'content': 'IMAZEO-2026', 'format': 'svg', 'includeText': False})
+```

imazeo-1.0.0/README.md

@@ -0,0 +1,183 @@
+# imazeo
+
+Official **server-side** Python SDK for Imazeo.
+
+|                |                                 |
+| -------------- | ------------------------------- |
+| Package        | `imazeo`                        |
+| SDK version    | `1.0.0`                         |
+| Default API    | `v1`                            |
+| Supported APIs | `v1`                            |
+| Runtime        | Python **3.10+** (sync `httpx`) |
+| Registry       | [PyPI](https://pypi.org/project/imazeo/) |
+| Source         | [GitHub](https://github.com/manishbalodia/imazeo-python) |
+
+> **Security:** Secret API keys (`X-API-Key`) are for trusted servers only.
+> Do **not** ship this client with a secret key in browsers or client apps.
+
+Integration contract and learning path: [GUIDE.md](GUIDE.md).
+
+## Install
+
+```bash
+pip install imazeo
+```
+
+Requires Python 3.10+. Create a project API key in the Imazeo customer portal.
+Default API origin is `https://api.imazeo.com` (override with `base_url` when needed).
+
+## Learning path
+
+Read the self-contained [integration guide](GUIDE.md) for project/key setup,
+language examples, PDF response types, pagination, output retention, troubleshooting
+and production practices.
+
+The default HTTP client refuses redirects so credentials stay on the configured
+API origin.
+
+## Quick start
+
+```python
+from pathlib import Path
+from imazeo import Imazeo
+import os
+
+client = Imazeo(
+    api_key=os.environ["IMAZEO_API_KEY"],
+    base_url=os.environ["IMAZEO_API_ORIGIN"],  # supplied API origin
+    # project_id="…",  # optional; otherwise resolved via /v1/api-key/context
+)
+
+qr = client.qr.generate({
+    "content": "https://imazeo.com",
+    "format": "png",
+    "size": 256,
+})
+Path("qr.png").write_bytes(qr.data)
+client.close()
+```
+
+Or use as a context manager:
+
+```python
+with Imazeo(api_key=os.environ["IMAZEO_API_KEY"]) as client:
+    ctx = client.context.get()
+    print(ctx["projectId"], ctx["keyId"])
+```
+
+## Authentication
+
+```python
+Imazeo(api_key=os.environ["IMAZEO_API_KEY"])
+```
+
+Sends `X-API-Key` only. Never send `Authorization` together with an API key
+(backend rejects that combination).
+
+## Resources
+
+| Resource            | Methods                                                                          |
+| ------------------- | -------------------------------------------------------------------------------- |
+| `client.context`    | `get()` → project/key IDs                                                        |
+| `client.images`     | `upload`, `list` (`page`/`limit`/`q`), `get`, `delete`, `download`               |
+| `client.transforms` | `create`, `list`, `get`, `download` (`if_none_match` → `not_modified`), `delete` |
+| `client.qr`         | `generate`                                                                       |
+| `client.barcodes`   | `generate`                                                                       |
+| `client.pdf`        | `info`, `render`, `merge`, `extract`                                             |
+
+### Upload + transform
+
+```python
+image = client.images.upload(
+    photo_bytes,
+    filename="photo.jpg",
+    content_type="image/jpeg",
+)
+
+out = client.transforms.create({
+    "imageId": image["_id"],
+    "mode": "EPHEMERAL",
+    "transform": {"width": 1200, "format": "webp", "quality": 85},
+})
+# out.data → bytes
+```
+
+### Remote URL transform
+
+```python
+out = client.transforms.create({
+    "url": "https://example.com/image.jpg",
+    "transform": {"width": 640, "format": "jpeg"},
+})
+```
+
+### PDF
+
+```python
+info = client.pdf.info(pdf_bytes)
+page = client.pdf.render(pdf_bytes, {"pages": "1", "format": "png"})
+merged = client.pdf.merge([pdf_a, pdf_b])
+extracted = client.pdf.extract(pdf_bytes, {"pages": "1,2"})
+```
+
+## Errors
+
+```python
+from imazeo import ImazeoError, RateLimitError
+
+try:
+    client.images.get(image_id)
+except RateLimitError as error:
+    print(error.code, error.request_id)
+except ImazeoError as error:
+    print(error.status, error.code, error.message)
+```
+
+## Configuration
+
+| Option        | Default                  | Notes                                  |
+| ------------- | ------------------------ | -------------------------------------- |
+| `api_key`     | required                 | Secret key                             |
+| `project_id`  | from context             | Path project                           |
+| `base_url`    | `https://api.imazeo.com` | Origin only; `/v1` stripped if present |
+| `api_version` | `v1`                     | Allowlisted                            |
+| `timeout_ms`  | `60000`                  | PDF uses 120s; QR/barcode 30s          |
+| `app_name`    | —                        | Appended to User-Agent                 |
+| `transport`   | —                        | Optional `httpx.BaseTransport` (tests) |
+
+## API version vs package version
+
+- **API** path version: `v1` (configured via `api_version`)
+- **SDK** SemVer: `1.0.0`
+
+`Imazeo.api_compatibility()` reports supported API versions.
+
+## Not included
+
+Portal JWT APIs (projects CRUD, API-key management, usage, plans, tickets, auth),
+admin APIs, tool-artifacts, outputs, and browser secret-key usage.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT
+
+## Media contract update — 2026-10-02
+
+Barcode generation requires `type` and string `content`; optional `format` is
+`png` or `svg` (default `png`), and `includeText` is a boolean (default `true`).
+The old `data`, `output` and `includetext` fields are removed before release.
+PDF merge sends repeated `file` parts in order. Omit optional fields for defaults;
+JSON numbers/booleans are not coerced and top-level optional nulls are rejected.
+Barcode scale and image hue are integers. Methods retain language-specific names.
+The reviewed API-key-only contract is bundled in `openapi/backend.json`.
+
+```python
+client.barcodes.generate({'type': 'code128', 'content': 'IMAZEO-2026', 'format': 'svg', 'includeText': False})
+```

imazeo-1.0.0/examples/qr.py

@@ -0,0 +1,44 @@
+"""Minimal server-side QR example.
+
+Requires: IMAZEO_API_KEY, optional IMAZEO_BASE_URL, IMAZEO_PROJECT_ID
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+from imazeo import Imazeo
+
+
+def main() -> None:
+    api_key = os.environ.get("IMAZEO_API_KEY")
+    if not api_key:
+        raise SystemExit("Set IMAZEO_API_KEY")
+
+    with Imazeo(
+        api_key=api_key,
+        base_url=os.environ.get("IMAZEO_BASE_URL", "http://localhost:3001"),
+        project_id=os.environ.get("IMAZEO_PROJECT_ID"),
+    ) as client:
+        ctx = client.context.get()
+        print("project", ctx["projectId"], "env", ctx["environment"])
+
+        qr = client.qr.generate(
+            {
+                "content": "https://imazeo.com",
+                "size": 256,
+                "format": "png",
+            }
+        )
+        Path("qr.png").write_bytes(qr.data)
+        print("wrote qr.png", qr.content_type)
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception as error:  # noqa: BLE001 — example script
+        print(error, file=sys.stderr)
+        raise SystemExit(1) from error