myocr-client 0.2.0__py3-none-any.whl

myocr_client/__init__.py

@@ -0,0 +1,63 @@
+"""myocr.app — Python SDK for the v1 API.
+
+    from myocr_client import MyOCRClient
+    client = MyOCRClient(api_key="sk_live_...")
+    result = client.convert("fattura.pdf", model="invoice")
+    result.save("out.xlsx")
+
+Async jobs (file grandi):
+    job = client.create_job("big.pdf", model="bank_statement",
+                            webhook_url="https://my.app/webhook")
+    job.wait()  # polling con backoff esponenziale
+    job.download("out.xlsx")
+"""
+from .client import MyOCRClient
+from .models import ConversionResult, Job, JobStatus, JobResult, BatchResult
+from .exceptions import (
+    MyOCRError,
+    MissingApiKey,
+    InvalidApiKey,
+    UnsupportedModel,
+    UnsupportedFileType,
+    MissingFile,
+    FileTooLarge,
+    TooManyPages,
+    InvalidWebhookUrl,
+    QuotaExceeded,
+    NotReady,
+    NotFound,
+    OcrEngineError,
+    StorageError,
+    ServiceNotReady,
+    RateLimited,
+    InternalError,
+)
+from .webhook import verify_webhook_signature
+
+__version__ = "0.2.0"
+__all__ = [
+    "MyOCRClient",
+    "ConversionResult",
+    "Job",
+    "JobStatus",
+    "JobResult",
+    "BatchResult",
+    "MyOCRError",
+    "MissingApiKey",
+    "InvalidApiKey",
+    "UnsupportedModel",
+    "UnsupportedFileType",
+    "MissingFile",
+    "FileTooLarge",
+    "TooManyPages",
+    "InvalidWebhookUrl",
+    "QuotaExceeded",
+    "NotReady",
+    "NotFound",
+    "OcrEngineError",
+    "StorageError",
+    "ServiceNotReady",
+    "RateLimited",
+    "InternalError",
+    "verify_webhook_signature",
+]

myocr_client/client.py

@@ -0,0 +1,374 @@
+"""Client principale per l'API myocr.app v1.
+
+Tutti i metodi sollevano sottoclassi di MyOCRError sui codici errore.
+Retry automatico su 429 e 5xx (3 tentativi, backoff esponenziale 1s/2s/4s).
+"""
+import logging
+import os
+import time
+from typing import Optional, BinaryIO, Union, List, IO
+
+try:
+    import requests
+except ImportError:
+    raise ImportError(
+        "myocr-client requires `requests`. Install with: pip install requests"
+    )
+
+from .exceptions import (
+    MyOCRError,
+    MissingApiKey,
+    RateLimited,
+    InternalError,
+    from_response,
+)
+from .models import ConversionResult, Job, JobResult, BatchResult, JobStatus
+
+
+DEFAULT_BASE_URL = "https://api.myocr.app"
+DEFAULT_TIMEOUT = 60  # seconds
+DEFAULT_RETRY_ATTEMPTS = 3
+RETRYABLE_STATUS = {429, 500, 502, 503, 504}
+
+logger = logging.getLogger(__name__)
+
+
+def _looks_like_path(file: Union[str, BinaryIO, bytes]) -> bool:
+    return isinstance(file, str) and os.path.exists(file)
+
+
+def _prepare_file_tuple(file, filename: Optional[str] = None):
+    """Normalizza l'input file in tupla (filename, fileobj-or-bytes) per requests."""
+    if isinstance(file, (bytes, bytearray)):
+        return (filename or "upload.pdf", bytes(file))
+    if hasattr(file, "read"):
+        name = filename or getattr(file, "name", None) or "upload.pdf"
+        if isinstance(name, str) and os.sep in name:
+            name = os.path.basename(name)
+        return (name, file)
+    if isinstance(file, str):
+        return (filename or os.path.basename(file), open(file, "rb"))
+    raise TypeError(f"file must be a path, file-like, or bytes; got {type(file)!r}")
+
+
+class MyOCRClient:
+    """Client HTTP per l'API myocr.app.
+
+    Args:
+        api_key: chiave 'sk_live_...' o 'sk_test_...' (o letta da env MYOCR_API_KEY)
+        base_url: default https://api.myocr.app (override per staging beta.myocr.app)
+        timeout: secondi per ogni HTTP request
+        retry_attempts: tentativi totali su 429 e 5xx (default 3)
+        session: opzionale requests.Session pre-configurato (proxy, certificati)
+
+    Esempio:
+        from myocr_client import MyOCRClient
+        client = MyOCRClient(api_key="sk_live_...")
+        result = client.convert("invoice.pdf", model="invoice")
+        result.save("out.xlsx")
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        retry_attempts: int = DEFAULT_RETRY_ATTEMPTS,
+        session: Optional["requests.Session"] = None,
+    ):
+        self.api_key = api_key or os.environ.get("MYOCR_API_KEY", "").strip()
+        if not self.api_key:
+            raise MissingApiKey(
+                "api_key required (pass as argument or set MYOCR_API_KEY env var)"
+            )
+        self.base_url = (base_url or os.environ.get("MYOCR_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+        self.timeout = timeout
+        self.retry_attempts = max(1, retry_attempts)
+        self._session = session or requests.Session()
+
+    def _headers(self) -> dict:
+        return {
+            "X-API-Key": self.api_key,
+            "User-Agent": "myocr-client-python/0.1.0",
+        }
+
+    def _request(self, method: str, path: str, **kwargs) -> "requests.Response":
+        """HTTP request con retry su 429/5xx."""
+        url = f"{self.base_url}{path}"
+        headers = kwargs.pop("headers", {})
+        headers.update(self._headers())
+        kwargs.setdefault("timeout", self.timeout)
+
+        last_exc = None
+        for attempt in range(self.retry_attempts):
+            try:
+                resp = self._session.request(method, url, headers=headers, **kwargs)
+            except requests.RequestException as e:
+                last_exc = e
+                if attempt < self.retry_attempts - 1:
+                    delay = 2 ** attempt
+                    logger.warning(f"[myocr] {method} {path} network error attempt {attempt + 1}: {e}; retry in {delay}s")
+                    time.sleep(delay)
+                    continue
+                raise InternalError(f"network error: {e}", status_code=0) from e
+
+            if resp.status_code in RETRYABLE_STATUS and attempt < self.retry_attempts - 1:
+                # Honor Retry-After se presente
+                retry_after = resp.headers.get("Retry-After")
+                try:
+                    delay = float(retry_after) if retry_after else 2 ** attempt
+                except (TypeError, ValueError):
+                    delay = 2 ** attempt
+                logger.warning(f"[myocr] {method} {path} → {resp.status_code} attempt {attempt + 1}; retry in {delay}s")
+                time.sleep(delay)
+                continue
+            return resp
+        if last_exc:
+            raise InternalError(str(last_exc), status_code=0) from last_exc
+        return resp  # type: ignore
+
+    def _raise_if_error(self, resp: "requests.Response") -> None:
+        """Se response non 2xx, solleva l'eccezione appropriata."""
+        if 200 <= resp.status_code < 300:
+            return
+        request_id = resp.headers.get("X-MyOCR-Request-Id")
+        try:
+            body = resp.json()
+        except ValueError:
+            body = resp.text
+        raise from_response(resp.status_code, body, request_id=request_id)
+
+    # ---------- Status ----------
+
+    def status(self) -> dict:
+        """GET /v1/status — health check pubblico (no auth richiesta ma la mandiamo comunque)."""
+        resp = self._request("GET", "/v1/status")
+        self._raise_if_error(resp)
+        return resp.json().get("data", {})
+
+    def usage(self) -> dict:
+        """GET /v1/usage — quota corrente per la propria API key.
+        Ritorna dict con plan/calls_used/calls_limit/percentage/reset_date/year_month/is_test_key.
+        Utile per controllare programmaticamente quando avvicinarsi al limite."""
+        resp = self._request("GET", "/v1/usage")
+        self._raise_if_error(resp)
+        return resp.json().get("data", {})
+
+    # ---------- Sync conversion ----------
+
+    def convert(
+        self,
+        file: Union[str, bytes, IO[bytes]],
+        model: str = "tables",
+        output: str = "xlsx",
+        filename: Optional[str] = None,
+    ) -> ConversionResult:
+        """POST /v1/convert — sync, max 5MB / 10 pagine.
+
+        Args:
+            file: path stringa, bytes, o file-like object aperto in 'rb'
+            model: tables / text / invoice / receipt / bank_statement / business_card
+            output: xlsx / txt / json
+            filename: nome originale (utile se file è bytes o file-like senza .name)
+
+        Returns:
+            ConversionResult con .content (bytes) o .data (dict per output=json).
+
+        Raises:
+            QuotaExceeded, FileTooLarge, TooManyPages, OcrEngineError, RateLimited, ...
+        """
+        file_tuple = _prepare_file_tuple(file, filename=filename)
+        files = {"file": file_tuple}
+        data = {"model": model, "output": output}
+        try:
+            resp = self._request("POST", "/v1/convert", files=files, data=data)
+        finally:
+            # se abbiamo aperto noi il file, chiudilo
+            if isinstance(file, str) and hasattr(file_tuple[1], "close"):
+                try:
+                    file_tuple[1].close()
+                except Exception:
+                    pass
+
+        self._raise_if_error(resp)
+
+        request_id = resp.headers.get("X-MyOCR-Request-Id")
+        pages_used_h = resp.headers.get("X-MyOCR-Pages-Used")
+        pages_used = int(pages_used_h) if pages_used_h and pages_used_h.isdigit() else None
+        model_used = resp.headers.get("X-MyOCR-Model") or model
+
+        ctype = resp.headers.get("Content-Type", "").lower()
+        if "application/json" in ctype:
+            body = resp.json()
+            return ConversionResult(
+                data=body.get("data") if isinstance(body, dict) else body,
+                format="json",
+                request_id=request_id,
+                pages_used=pages_used,
+                model=model_used,
+            )
+        if "text/plain" in ctype:
+            return ConversionResult(
+                content=resp.content,
+                format="txt",
+                request_id=request_id,
+                pages_used=pages_used,
+                model=model_used,
+            )
+        return ConversionResult(
+            content=resp.content,
+            format="xlsx",
+            request_id=request_id,
+            pages_used=pages_used,
+            model=model_used,
+        )
+
+    # ---------- Async jobs ----------
+
+    def create_job(
+        self,
+        file: Union[str, bytes, IO[bytes]],
+        model: str = "tables",
+        webhook_url: Optional[str] = None,
+        filename: Optional[str] = None,
+    ) -> Job:
+        """POST /v1/jobs — async, max 50MB."""
+        file_tuple = _prepare_file_tuple(file, filename=filename)
+        files = {"file": file_tuple}
+        data = {"model": model}
+        if webhook_url:
+            data["webhook_url"] = webhook_url
+        try:
+            resp = self._request("POST", "/v1/jobs", files=files, data=data)
+        finally:
+            if isinstance(file, str) and hasattr(file_tuple[1], "close"):
+                try:
+                    file_tuple[1].close()
+                except Exception:
+                    pass
+
+        self._raise_if_error(resp)
+        body = resp.json().get("data", {})
+        return Job.from_dict(body, client=self)
+
+    def get_job(self, request_id: str) -> Job:
+        """GET /v1/jobs/{id}."""
+        resp = self._request("GET", f"/v1/jobs/{request_id}")
+        self._raise_if_error(resp)
+        return Job.from_dict(resp.json().get("data", {}), client=self)
+
+    def get_job_result(self, request_id: str) -> JobResult:
+        """GET /v1/jobs/{id}/result — signed URL R2 o file binario."""
+        resp = self._request("GET", f"/v1/jobs/{request_id}/result")
+        self._raise_if_error(resp)
+        ctype = resp.headers.get("Content-Type", "").lower()
+        if "application/json" in ctype:
+            body = resp.json().get("data", {})
+            return JobResult(
+                result_url=body.get("result_url"),
+                expires_in=body.get("expires_in"),
+            )
+        return JobResult(
+            content=resp.content,
+            content_type=ctype or None,
+        )
+
+    def delete_job(self, request_id: str) -> dict:
+        """DELETE /v1/jobs/{id}."""
+        resp = self._request("DELETE", f"/v1/jobs/{request_id}")
+        self._raise_if_error(resp)
+        return resp.json().get("data", {})
+
+    # ---------- Batch ----------
+
+    def batch(
+        self,
+        files: List[Union[str, bytes, IO[bytes]]],
+        model: str = "tables",
+        webhook_url: Optional[str] = None,
+        filenames: Optional[List[str]] = None,
+    ) -> BatchResult:
+        """POST /v1/batch — 1-20 file in una chiamata."""
+        if not files:
+            raise ValueError("files list cannot be empty")
+        if len(files) > 20:
+            raise ValueError("max 20 files per batch")
+
+        names = filenames or [None] * len(files)
+        if len(names) != len(files):
+            raise ValueError("filenames length must match files length")
+
+        multi_files = []
+        opened = []
+        for f, name in zip(files, names):
+            tup = _prepare_file_tuple(f, filename=name)
+            multi_files.append(("files", tup))
+            if isinstance(f, str):
+                opened.append(tup[1])
+
+        data = {"model": model}
+        if webhook_url:
+            data["webhook_url"] = webhook_url
+
+        try:
+            resp = self._request("POST", "/v1/batch", files=multi_files, data=data)
+        finally:
+            for fh in opened:
+                try:
+                    fh.close()
+                except Exception:
+                    pass
+
+        self._raise_if_error(resp)
+        body = resp.json().get("data", {})
+        return BatchResult(
+            batch_id=body.get("batch_id", ""),
+            model=body.get("model", model),
+            jobs=[
+                Job(
+                    request_id=j.get("request_id", ""),
+                    status=JobStatus(j.get("status", "pending")),
+                    model=body.get("model", model),
+                    _client=self,
+                )
+                for j in body.get("jobs", [])
+            ],
+            errors=body.get("errors", []),
+        )
+
+    # ---------- API keys (richiede session login utente, non X-API-Key) ----------
+    # Esposte per completeness; uso reale dal dashboard /account/api.
+
+    def list_keys(self) -> List[dict]:
+        """GET /v1/keys — lista keys utente (richiede session cookie, non X-API-Key)."""
+        resp = self._request("GET", "/v1/keys")
+        self._raise_if_error(resp)
+        return resp.json().get("data", [])
+
+    def rotate_key(self, key_id: int) -> dict:
+        """POST /v1/keys/{id}/rotate — revoca + nuova in atomica.
+        Ritorna dict con 'key' (raw) mostrato una sola volta. Salvalo subito.
+        Richiede session login (non X-API-Key)."""
+        resp = self._request("POST", f"/v1/keys/{key_id}/rotate")
+        self._raise_if_error(resp)
+        return resp.json().get("data", {})
+
+    def list_jobs(
+        self,
+        status: Optional[str] = None,
+        model: Optional[str] = None,
+        limit: int = 20,
+        offset: int = 0,
+    ) -> dict:
+        """GET /v1/jobs — lista paginata job per la propria api_key.
+        Filtri: status (pending/processing/done/failed), model. limit max 100.
+        Ritorna {total, limit, offset, jobs: [...]}."""
+        params = {"limit": str(min(limit, 100)), "offset": str(max(offset, 0))}
+        if status:
+            params["status"] = status
+        if model:
+            params["model"] = model
+        from urllib.parse import urlencode
+        resp = self._request("GET", f"/v1/jobs?{urlencode(params)}")
+        self._raise_if_error(resp)
+        return resp.json().get("data", {})

myocr_client/exceptions.py

@@ -0,0 +1,195 @@
+"""Mappa 1:1 sui codici errore dell'API v1 (vedi static/openapi.yaml).
+
+Tutte le eccezioni custom ereditano da MyOCRError. Il client le solleva
+sulla base del campo `error.code` dell'envelope JSON, oppure dello status HTTP
+quando il body non è JSON.
+
+Esempio:
+    try:
+        client.convert("doc.pdf", model="invoice")
+    except QuotaExceeded as e:
+        print(e.upgrade_url)
+    except InvalidApiKey:
+        print("revoke or rotate key")
+"""
+from typing import Optional
+
+
+class MyOCRError(Exception):
+    """Base per tutte le eccezioni dell'SDK."""
+
+    def __init__(
+        self,
+        message: str = "",
+        *,
+        code: Optional[str] = None,
+        request_id: Optional[str] = None,
+        status_code: Optional[int] = None,
+        payload: Optional[dict] = None,
+    ):
+        super().__init__(message or code or "myocr error")
+        self.code = code
+        self.message = message
+        self.request_id = request_id
+        self.status_code = status_code
+        self.payload = payload or {}
+
+    def __repr__(self) -> str:
+        return (
+            f"{self.__class__.__name__}(code={self.code!r}, "
+            f"status={self.status_code}, request_id={self.request_id!r}, "
+            f"message={self.message!r})"
+        )
+
+
+class MissingApiKey(MyOCRError):
+    """X-API-Key header assente."""
+
+
+class InvalidApiKey(MyOCRError):
+    """Key non trovata o revocata."""
+
+
+class UnsupportedModel(MyOCRError):
+    """Parametro model non in tables/text/invoice/receipt/bank_statement/business_card."""
+
+
+class UnsupportedFileType(MyOCRError):
+    """Estensione file non supportata."""
+
+
+class MissingFile(MyOCRError):
+    """Multipart file mancante o vuoto."""
+
+
+class FileTooLarge(MyOCRError):
+    """File supera 5MB (sync) o 50MB (async)."""
+
+
+class TooManyPages(MyOCRError):
+    """Documento supera 10 pagine sul flow sync."""
+
+
+class InvalidWebhookUrl(MyOCRError):
+    """webhook_url non http(s)://."""
+
+
+class QuotaExceeded(MyOCRError):
+    """Quota mensile esaurita (status 402).
+
+    Attributi extra letti dal payload error:
+        upgrade_url   — URL dashboard per upgrade
+        calls_used    — chiamate consumate questo mese
+        calls_limit   — limite piano corrente
+        reset_date    — ISO date del reset
+        current_plan  — nome piano attuale
+    """
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        err = self.payload.get("error") if isinstance(self.payload, dict) else None
+        if isinstance(err, dict):
+            self.upgrade_url = err.get("upgrade_url")
+            self.calls_used = err.get("calls_used")
+            self.calls_limit = err.get("calls_limit")
+            self.reset_date = err.get("reset_date")
+            self.current_plan = err.get("current_plan")
+        else:
+            self.upgrade_url = None
+            self.calls_used = None
+            self.calls_limit = None
+            self.reset_date = None
+            self.current_plan = None
+
+
+class NotReady(MyOCRError):
+    """Risultato job richiesto prima che status=done."""
+
+
+class NotFound(MyOCRError):
+    """Job/key non trovato."""
+
+
+class OcrEngineError(MyOCRError):
+    """Errore upstream del motore OCR (502)."""
+
+
+class StorageError(MyOCRError):
+    """Errore object storage (R2)."""
+
+
+class ServiceNotReady(MyOCRError):
+    """Endpoint non ancora attivo (503)."""
+
+
+class RateLimited(MyOCRError):
+    """Rate limit superato (429)."""
+
+
+class InternalError(MyOCRError):
+    """Errore server generico (500)."""
+
+
+# Mapping codice errore API → eccezione SDK
+CODE_TO_EXCEPTION = {
+    "MISSING_API_KEY": MissingApiKey,
+    "INVALID_API_KEY": InvalidApiKey,
+    "UNSUPPORTED_MODEL": UnsupportedModel,
+    "UNSUPPORTED_FILE_TYPE": UnsupportedFileType,
+    "MISSING_FILE": MissingFile,
+    "FILE_TOO_LARGE": FileTooLarge,
+    "TOO_MANY_PAGES": TooManyPages,
+    "INVALID_WEBHOOK_URL": InvalidWebhookUrl,
+    "QUOTA_EXCEEDED": QuotaExceeded,
+    "INSUFFICIENT_CREDITS": QuotaExceeded,
+    "quota_exceeded": QuotaExceeded,
+    "NOT_READY": NotReady,
+    "NOT_FOUND": NotFound,
+    "OCR_ERROR": OcrEngineError,
+    "STORAGE_ERROR": StorageError,
+    "SERVICE_NOT_READY": ServiceNotReady,
+    "INTERNAL_ERROR": InternalError,
+}
+
+
+def from_response(status_code: int, body, request_id: Optional[str] = None) -> MyOCRError:
+    """Costruisce l'eccezione appropriata da una response HTTP non 2xx."""
+    code = None
+    message = ""
+    payload = None
+    if isinstance(body, dict):
+        payload = body
+        err = body.get("error")
+        if isinstance(err, dict):
+            code = err.get("code")
+            message = err.get("message", "")
+        elif isinstance(err, str):
+            code = err
+            message = body.get("message", "")
+    elif isinstance(body, (bytes, str)):
+        message = body.decode("utf-8", errors="replace") if isinstance(body, bytes) else body
+
+    if status_code == 429:
+        return RateLimited(message or "Rate limit exceeded", code=code or "RATE_LIMITED",
+                           status_code=status_code, request_id=request_id, payload=payload)
+
+    if code and code in CODE_TO_EXCEPTION:
+        return CODE_TO_EXCEPTION[code](message or code, code=code,
+                                       status_code=status_code, request_id=request_id, payload=payload)
+
+    # Fallback per status code senza body strutturato
+    if status_code == 401:
+        return InvalidApiKey(message or "Unauthorized", code=code, status_code=status_code,
+                             request_id=request_id, payload=payload)
+    if status_code == 404:
+        return NotFound(message or "Not found", code=code, status_code=status_code,
+                        request_id=request_id, payload=payload)
+    if status_code == 402:
+        return QuotaExceeded(message or "Quota exceeded", code=code, status_code=status_code,
+                             request_id=request_id, payload=payload)
+    if status_code >= 500:
+        return InternalError(message or f"Server error ({status_code})", code=code,
+                             status_code=status_code, request_id=request_id, payload=payload)
+
+    return MyOCRError(message or f"HTTP {status_code}", code=code, status_code=status_code,
+                      request_id=request_id, payload=payload)

myocr_client/models.py

@@ -0,0 +1,201 @@
+"""Modelli dati restituiti dall'SDK."""
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Optional, List, Any, Dict
+
+
+class JobStatus(str, Enum):
+    PENDING = "pending"
+    PROCESSING = "processing"
+    DONE = "done"
+    FAILED = "failed"
+
+
+@dataclass
+class ConversionResult:
+    """Risultato di `client.convert(...)`.
+
+    Tre forme possibili in base al model/output:
+    - xlsx binario: `content` è bytes, `format='xlsx'`
+    - txt: `content` è bytes/str, `format='txt'`
+    - json metadata: `data` è dict, `format='json'`
+    """
+
+    content: Optional[bytes] = None
+    data: Optional[Dict[str, Any]] = None
+    format: str = "xlsx"
+    request_id: Optional[str] = None
+    pages_used: Optional[int] = None
+    model: Optional[str] = None
+
+    def save(self, path: str) -> None:
+        """Scrive il contenuto su disk. Per format='json' usa data via .json invece."""
+        if self.content is None:
+            raise ValueError(
+                "ConversionResult has no binary content (format=json). "
+                "Use `result.data` or `result.json()` instead."
+            )
+        with open(path, "wb") as f:
+            f.write(self.content)
+
+    def text(self) -> str:
+        """Decodifica come UTF-8 — utile per format='txt'."""
+        if self.content is None:
+            return ""
+        return self.content.decode("utf-8", errors="replace")
+
+    def json(self) -> Dict[str, Any]:
+        """Ritorna il dict data (format='json') o solleva."""
+        if self.data is None:
+            raise ValueError("ConversionResult has no JSON data (format != 'json')")
+        return self.data
+
+
+@dataclass
+class JobResult:
+    """Wrapper risultato per /v1/jobs/{id}/result.
+
+    Due forme:
+    - signed URL R2: `result_url` settato, `expires_in` in secondi
+    - file binario diretto: `content` bytes
+    """
+
+    result_url: Optional[str] = None
+    expires_in: Optional[int] = None
+    content: Optional[bytes] = None
+    content_type: Optional[str] = None
+
+    def save(self, path: str) -> None:
+        """Salva il file. Se result_url è settato, scarica dal signed URL."""
+        if self.content is not None:
+            with open(path, "wb") as f:
+                f.write(self.content)
+            return
+        if self.result_url:
+            import urllib.request
+            with urllib.request.urlopen(self.result_url, timeout=60) as resp:
+                data = resp.read()
+            with open(path, "wb") as f:
+                f.write(data)
+            return
+        raise ValueError("JobResult has neither content nor result_url")
+
+
+@dataclass
+class Job:
+    """Job async. Restituito da create_job() e get_job().
+
+    Usare `job.wait()` per polling fino a `done`/`failed`.
+    """
+
+    request_id: str
+    status: JobStatus
+    model: Optional[str] = None
+    pages_used: Optional[int] = None
+    created_at: Optional[str] = None
+    completed_at: Optional[str] = None
+    error_detail: Optional[str] = None
+    _client: Any = field(default=None, repr=False)
+
+    @classmethod
+    def from_dict(cls, d: dict, client=None) -> "Job":
+        return cls(
+            request_id=d.get("request_id", ""),
+            status=JobStatus(d.get("status", "pending")),
+            model=d.get("model"),
+            pages_used=d.get("pages_used"),
+            created_at=d.get("created_at"),
+            completed_at=d.get("completed_at"),
+            error_detail=d.get("error_detail"),
+            _client=client,
+        )
+
+    @property
+    def is_done(self) -> bool:
+        return self.status == JobStatus.DONE
+
+    @property
+    def is_failed(self) -> bool:
+        return self.status == JobStatus.FAILED
+
+    @property
+    def is_terminal(self) -> bool:
+        return self.status in (JobStatus.DONE, JobStatus.FAILED)
+
+    def refresh(self) -> "Job":
+        """Ri-leggi lo stato dal server. Richiede il client originario."""
+        if self._client is None:
+            raise RuntimeError("Job not bound to a client (use client.get_job(request_id))")
+        updated = self._client.get_job(self.request_id)
+        # in-place update dei campi
+        self.status = updated.status
+        self.pages_used = updated.pages_used
+        self.completed_at = updated.completed_at
+        self.error_detail = updated.error_detail
+        return self
+
+    def wait(self, timeout: float = 600.0, initial_delay: float = 1.0,
+             max_delay: float = 15.0) -> "Job":
+        """Polling con backoff esponenziale finché lo stato è terminale.
+
+        timeout: secondi totali prima di sollevare TimeoutError.
+        Default: 10 min, retry a 1s,2s,4s,8s,15s,15s,...
+        """
+        import time
+        deadline = time.monotonic() + timeout
+        delay = initial_delay
+        while True:
+            self.refresh()
+            if self.is_terminal:
+                return self
+            if time.monotonic() >= deadline:
+                raise TimeoutError(
+                    f"Job {self.request_id} still {self.status.value} after {timeout}s"
+                )
+            time.sleep(min(delay, max(0.1, deadline - time.monotonic())))
+            delay = min(delay * 2, max_delay)
+
+    def get_result(self) -> JobResult:
+        """Richiede /v1/jobs/{id}/result. Solleva NotReady se status != done."""
+        if self._client is None:
+            raise RuntimeError("Job not bound to a client")
+        return self._client.get_job_result(self.request_id)
+
+    def download(self, path: str) -> None:
+        """Shortcut: get_result().save(path)."""
+        self.get_result().save(path)
+
+    def delete(self) -> None:
+        """Cancella job + cleanup file."""
+        if self._client is None:
+            raise RuntimeError("Job not bound to a client")
+        self._client.delete_job(self.request_id)
+
+
+@dataclass
+class BatchResult:
+    """Risultato di `client.batch(...)`. Misto: jobs creati + errori per-file."""
+
+    batch_id: str
+    model: str
+    jobs: List[Job] = field(default_factory=list)
+    errors: List[Dict[str, Any]] = field(default_factory=list)
+
+    @property
+    def jobs_created(self) -> int:
+        return len(self.jobs)
+
+    def wait_all(self, timeout: float = 1200.0, parallel: bool = True, max_workers: int = 10) -> List[Job]:
+        """Polling fino a stato terminale per tutti i job.
+
+        Args:
+            timeout: secondi per ogni singolo job
+            parallel: se True (default), usa ThreadPoolExecutor per pollare in parallelo.
+                Per 20 job, ~20× più veloce di sequenziale quando dominato da network.
+            max_workers: thread max (default 10). I/O bound quindi sicuro alzare.
+        """
+        if not parallel or len(self.jobs) <= 1:
+            return [j.wait(timeout=timeout) for j in self.jobs]
+        from concurrent.futures import ThreadPoolExecutor
+        with ThreadPoolExecutor(max_workers=min(max_workers, len(self.jobs))) as ex:
+            return list(ex.map(lambda j: j.wait(timeout=timeout), self.jobs))

myocr_client/webhook.py

@@ -0,0 +1,68 @@
+"""Helper per verificare la firma HMAC dei webhook in entrata.
+
+myocr firma ogni webhook con header `X-MyOCR-Signature: sha256=<hex>` calcolato
+come HMAC-SHA256 del body grezzo, usando come chiave il `WEBHOOK_SIGNING_SECRET`
+che hai configurato lato server.
+
+Esempio (Flask):
+
+    from flask import request
+    from myocr_client import verify_webhook_signature, MyOCRError
+
+    @app.route("/webhooks/myocr", methods=["POST"])
+    def myocr_webhook():
+        body = request.get_data()  # raw bytes, non json parsed!
+        sig = request.headers.get("X-MyOCR-Signature", "")
+        if not verify_webhook_signature(body, sig, secret="my-shared-secret"):
+            return "invalid signature", 401
+        event = request.get_json()
+        # event = {"event": "job.completed", "data": {"request_id": "...", ...}}
+        return "", 200
+
+Importante: usa `request.get_data()` (raw), NON `request.get_json()` — la firma
+è calcolata sul body byte-per-byte come ricevuto, non sul JSON ri-serializzato.
+"""
+import hashlib
+import hmac
+from typing import Union
+
+
+def verify_webhook_signature(
+    body: Union[bytes, str],
+    signature: str,
+    secret: str,
+) -> bool:
+    """Verifica HMAC-SHA256 del body con segreto condiviso.
+
+    Args:
+        body: raw bytes ricevuti (NON il JSON parsato).
+        signature: valore header 'X-MyOCR-Signature' (formato 'sha256=<hex>').
+        secret: WEBHOOK_SIGNING_SECRET condiviso col server myocr.
+
+    Returns:
+        True se la firma è valida, False altrimenti.
+
+    Usa hmac.compare_digest per evitare timing attacks.
+    """
+    if not signature or not secret:
+        return False
+    if isinstance(body, str):
+        body = body.encode("utf-8")
+    if not isinstance(secret, str):
+        secret = str(secret)
+
+    # Formato atteso: "sha256=<hex>"
+    expected_prefix = "sha256="
+    if signature.startswith(expected_prefix):
+        received = signature[len(expected_prefix):].strip()
+    else:
+        # Permettiamo anche solo l'hex per tolleranza
+        received = signature.strip()
+
+    computed = hmac.new(
+        secret.encode("utf-8"),
+        body,
+        hashlib.sha256,
+    ).hexdigest()
+
+    return hmac.compare_digest(received, computed)

myocr_client-0.2.0.dist-info/METADATA

@@ -0,0 +1,274 @@
+Metadata-Version: 2.5
+Name: myocr-client
+Version: 0.2.0
+Summary: Official Python SDK for myocr.app — convert PDFs and images to structured Excel using myocr's OCR engine.
+Project-URL: Homepage, https://www.myocr.app
+Project-URL: Documentation, https://www.myocr.app/docs/api
+Project-URL: Repository, https://github.com/Selaf688/myocr-3.5
+Project-URL: Bug Tracker, https://github.com/Selaf688/myocr-3.5/issues
+Project-URL: Changelog, https://github.com/Selaf688/myocr-3.5/blob/main/sdk/python/CHANGELOG.md
+Author-email: "MAD.AI SRL" <info@myocr.app>
+License: MIT
+License-File: LICENSE
+Keywords: api-client,document-extraction,excel,myocr,ocr,pdf
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+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 :: Office/Business :: Office Suites
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Requires-Dist: requests>=2.28
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: responses>=0.23; extra == 'dev'
+Requires-Dist: twine>=4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# myocr-client — Python SDK for myocr.app
+
+Official Python client for the **[myocr.app](https://www.myocr.app)** API. Convert PDFs and images to structured Excel using myocr's OCR engine (invoice, receipt, bank statement, business card, generic tables, plain text).
+
+[![PyPI version](https://img.shields.io/pypi/v/myocr-client.svg)](https://pypi.org/project/myocr-client/)
+[![Python versions](https://img.shields.io/pypi/pyversions/myocr-client.svg)](https://pypi.org/project/myocr-client/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## Install
+
+```bash
+pip install myocr-client
+```
+
+## Quick start
+
+Get an API key at [/account/api](https://www.myocr.app/account/api) (signup required), then:
+
+```python
+from myocr_client import MyOCRClient
+
+client = MyOCRClient(api_key="sk_live_...")
+# or set MYOCR_API_KEY in env
+
+# Synchronous conversion (≤5MB, ≤10 pages, returns immediately)
+result = client.convert("invoice.pdf", model="invoice")
+result.save("invoice.xlsx")
+
+print(result.pages_used, result.model, result.request_id)
+```
+
+## Models
+
+| Model | Output | Best for |
+|---|---|---|
+| `tables` | xlsx with generic tables | Any structured table |
+| `text` | plain txt | OCR text extraction |
+| `invoice` | xlsx with Vendor / Customer / Total / Line items | Invoices, bills |
+| `receipt` | xlsx with Merchant / Date / Items / Total | Receipts |
+| `bank_statement` | xlsx with Account / Transactions sheet | Bank statements |
+| `business_card` | xlsx with Contact / Company / Phones / Emails | Business cards |
+
+## Async jobs (files > 5MB or > 10 pages)
+
+```python
+job = client.create_job(
+    "annual_report.pdf",
+    model="bank_statement",
+    webhook_url="https://your.app/webhooks/myocr",  # optional
+)
+
+# Option 1: polling with exponential backoff
+job.wait(timeout=600)
+job.download("report.xlsx")
+
+# Option 2: notified via webhook (preferred for prod) — see "Webhook verification" below
+```
+
+## Batch (1–20 files in one call)
+
+```python
+result = client.batch(
+    ["a.pdf", "b.pdf", "c.pdf"],
+    model="invoice",
+    webhook_url="https://your.app/webhooks/myocr",
+)
+print(result.jobs_created, "jobs queued;", len(result.errors), "errors")
+
+# Wait for all and download
+for job in result.wait_all(timeout=1200):
+    if job.is_done:
+        job.download(f"{job.request_id}.xlsx")
+```
+
+## Webhook verification
+
+myocr signs every webhook with HMAC-SHA256 (header `X-MyOCR-Signature: sha256=<hex>`). Always verify before trusting the payload — and **use raw bytes**, not the parsed JSON:
+
+```python
+from flask import Flask, request
+from myocr_client import verify_webhook_signature
+
+app = Flask(__name__)
+SECRET = "your-shared-secret"   # same as server WEBHOOK_SIGNING_SECRET
+
+@app.route("/webhooks/myocr", methods=["POST"])
+def myocr_webhook():
+    body = request.get_data()  # raw bytes, NOT request.get_json()
+    sig = request.headers.get("X-MyOCR-Signature", "")
+    if not verify_webhook_signature(body, sig, SECRET):
+        return "invalid signature", 401
+
+    event = request.get_json()  # safe now
+    # {"event": "job.completed", "data": {"request_id": "...", "status": "done", ...}}
+    return "", 200
+```
+
+Events: `job.completed`, `job.failed`.
+Retry policy: 1m → 5m → 30m → 2h (4 retries beyond the first attempt).
+
+## Error handling
+
+Every error code maps to a typed exception:
+
+```python
+from myocr_client import MyOCRClient, QuotaExceeded, InvalidApiKey, OcrEngineError
+
+client = MyOCRClient(api_key="sk_live_...")
+
+try:
+    result = client.convert("doc.pdf", model="invoice")
+except QuotaExceeded as e:
+    print(f"Plan {e.current_plan}, used {e.calls_used}/{e.calls_limit}")
+    print(f"Upgrade: {e.upgrade_url}")
+    print(f"Resets: {e.reset_date}")
+except InvalidApiKey:
+    print("Rotate your key from /account/api")
+except OcrEngineError:
+    print("OCR engine upstream failure; safe to retry")
+```
+
+| Exception | HTTP | Code |
+|---|---|---|
+| `MissingApiKey` | 401 | `MISSING_API_KEY` |
+| `InvalidApiKey` | 401 | `INVALID_API_KEY` |
+| `UnsupportedModel` | 400 | `UNSUPPORTED_MODEL` |
+| `UnsupportedFileType` | 400 | `UNSUPPORTED_FILE_TYPE` |
+| `MissingFile` | 400 | `MISSING_FILE` |
+| `FileTooLarge` | 413 | `FILE_TOO_LARGE` |
+| `TooManyPages` | 413 | `TOO_MANY_PAGES` |
+| `InvalidWebhookUrl` | 400 | `INVALID_WEBHOOK_URL` |
+| `QuotaExceeded` | 402 | `QUOTA_EXCEEDED` |
+| `NotReady` | 409 | `NOT_READY` |
+| `NotFound` | 404 | `NOT_FOUND` |
+| `OcrEngineError` | 502 | `OCR_ERROR` |
+| `StorageError` | 503 | `STORAGE_ERROR` |
+| `RateLimited` | 429 | — |
+| `ServiceNotReady` | 503 | `SERVICE_NOT_READY` |
+| `InternalError` | 500 | `INTERNAL_ERROR` |
+
+The SDK automatically retries `429` and `5xx` responses up to 3 times with exponential backoff (honoring `Retry-After` when present). After retries exhausted the exception is raised.
+
+## Input flexibility
+
+`client.convert()` and `client.create_job()` accept:
+
+- A file path: `client.convert("/path/to/doc.pdf", ...)`
+- Raw bytes: `client.convert(pdf_bytes, filename="doc.pdf", ...)`
+- A file-like object: `with open("doc.pdf", "rb") as f: client.convert(f, ...)`
+
+## Configuration
+
+| Argument | Env var | Default |
+|---|---|---|
+| `api_key` | `MYOCR_API_KEY` | — (required) |
+| `base_url` | `MYOCR_BASE_URL` | `https://api.myocr.app` |
+| `timeout` | — | 60s |
+| `retry_attempts` | — | 3 |
+| `session` | — | new `requests.Session()` |
+
+For staging:
+
+```python
+client = MyOCRClient(api_key="sk_test_...", base_url="https://beta.myocr.app")
+```
+
+## Monitor your quota
+
+Check current month usage programmatically (e.g. to upgrade before exhaustion):
+
+```python
+usage = client.usage()
+# {
+#   "plan": "free", "calls_used": 42, "calls_limit": 100,
+#   "percentage": 42.0, "reset_date": "2026-06-01T00:00:00",
+#   "year_month": "2026-05", "is_test_key": False
+# }
+if usage["percentage"] and usage["percentage"] > 80:
+    # alert ops, upgrade plan, or stop background workers
+    ...
+```
+
+## Status & limits
+
+```python
+status = client.status()
+# {
+#   "service": "myocr.app API", "version": "v1",
+#   "models_supported": ["bank_statement", "business_card", ...],
+#   "features": {"sync_convert": True, "async_jobs": True, "webhook": True, ...},
+#   "limits": {"sync_max_bytes": 5242880, "sync_max_pages": 10,
+#              "jobs_max_bytes": 52428800, "sync_rate_per_minute": 60,
+#              "jobs_rate_per_minute": 120}
+# }
+```
+
+## Rate limits (server-side)
+
+| Endpoint | Limit |
+|---|---|
+| `POST /v1/convert` | 60 / min |
+| `POST /v1/jobs` | 120 / min |
+| `POST /v1/batch` | 30 / min |
+
+The SDK handles `429` with automatic retry. If you saturate the quota, upgrade your plan from the dashboard.
+
+## Reference
+
+- **Full OpenAPI spec:** [openapi.yaml](https://www.myocr.app/static/openapi.yaml)
+- **Interactive docs:** [/docs/api](https://www.myocr.app/docs/api) (Scalar UI)
+- **Dashboard:** [/account/api](https://www.myocr.app/account/api) — manage keys, view usage, upgrade
+- **Webhook signing secret:** generated when you create a webhook integration; shared via dashboard.
+
+## Development
+
+```bash
+git clone https://github.com/Selaf688/myocr-3.5
+cd myocr-3.5/sdk/python
+pip install -e ".[dev]"
+pytest -v
+```
+
+## Versioning
+
+Semantic versioning. The API itself is `v1` and stable; the SDK can release patch/minor independently.
+
+## License
+
+MIT. See [LICENSE](./LICENSE).
+
+## Support
+
+- Documentation: <https://www.myocr.app/docs/api>
+- Email: info@myocr.app
+- Issues: <https://github.com/Selaf688/myocr-3.5/issues>

myocr_client-0.2.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+myocr_client/__init__.py,sha256=98unZ8qK-HnFMZRS_3zbw8LWTi1ixmCVnuvvabSWQAc,1493
+myocr_client/client.py,sha256=HO5FSSggcKpzWFCqX7jSm571aL3uYw3qF3iyQKfgXck,13936
+myocr_client/exceptions.py,sha256=MMmjzztMSPa6uXGZ6TWxW3VBAVxuHH228Y-9aT4rDo4,6273
+myocr_client/models.py,sha256=BtcYEb8N_N9N6w494mtoNFrYZsz6Dk0VeSOKY3oqLMU,6948
+myocr_client/webhook.py,sha256=aYeUINjAHCzgeGpaQSnuB9auX91Q7kkb2t4NaBmVNXE,2203
+myocr_client-0.2.0.dist-info/METADATA,sha256=0t6cXbu53sWi7lSf5leO2RMGLTBTdBwcpK-fwDOIUnw,9198
+myocr_client-0.2.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+myocr_client-0.2.0.dist-info/licenses/LICENSE,sha256=XOo4nn9CoGzqCDnfV2Mk2Nt_-g0RJ1xM_775tuWQ9Bo,1067
+myocr_client-0.2.0.dist-info/RECORD,,

myocr_client-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

myocr_client-0.2.0.dist-info/licenses/LICENSE

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