parseur-py 0.0.1__py3-none-any.whl

parseur/__init__.py

@@ -0,0 +1,31 @@
+from pathlib import Path
+
+from parseur.config import Config
+from parseur.document import Document, DocumentOrderKey
+from parseur.event import ParseurEvent
+from parseur.mailbox import Mailbox, MailboxOrderKey
+from parseur.schemas.document import DocumentStatus
+from parseur.utils import to_json
+from parseur.webhook import Webhook
+
+__all__ = [
+    "Config",
+    "Document",
+    "DocumentOrderKey",
+    "DocumentStatus",
+    "Mailbox",
+    "MailboxOrderKey",
+    "ParseurEvent",
+    "Webhook",
+    "to_json",
+]
+
+
+CONFIG_PATH = Path.home() / ".parseur.conf"
+config = Config(CONFIG_PATH)
+config.load()
+
+DEFAULT_API_BASE = "https://api.parseur.com"
+
+api_key = config.api_key
+api_base = config.api_base or DEFAULT_API_BASE

parseur/cli.py

@@ -0,0 +1,346 @@
+import sys
+
+import click
+
+import parseur
+
+
+@click.group()
+def cli():
+    """Parseur CLI - manage Parseur.com from the command line."""
+    pass
+
+
+@cli.command()
+@click.option(
+    "--api-key",
+    required=True,
+    help="Your Parseur API key",
+)
+@click.option(
+    "--api-base",
+    default=parseur.DEFAULT_API_BASE,
+    help="Optional API base URL",
+)
+def init(api_key, api_base):
+    """Initialize the CLI with your API token and optional base URL."""
+    config = parseur.Config(parseur.CONFIG_PATH)
+    config.api_key = api_key
+    config.api_base = api_base
+    config.save()
+    click.echo(f"✅ Parseur CLI initialized and config saved to {parseur.CONFIG_PATH}")
+
+
+# ------------------------
+# Mailbox commands
+# ------------------------
+
+
+@cli.command("list-mailboxes")
+@click.option("--search", help="Search string (mailbox name or email prefix)")
+@click.option(
+    "--order-by",
+    type=click.Choice([e.value for e in parseur.MailboxOrderKey]),
+    help=(
+        "Order by field. Use one of: "
+        "name, document_count, template_count, "
+        "PARSEDOK_count (processed), PARSEDKO_count (failed), "
+        "QUOTAEXC_count (quota exceeded), EXPORTKO_count (export failed)"
+    ),
+)
+@click.option(
+    "--descending/--ascending",
+    default=False,
+    help="Sort descending (default is ascending)",
+)
+def list_mailboxes(search, order_by, descending):
+    """
+    List all mailboxes with optional filtering and sorting.
+    """
+
+    order_by_enum = parseur.MailboxOrderKey(order_by) if order_by else None
+
+    mailboxes = parseur.Mailbox.list(
+        search=search,
+        order_by=order_by_enum,
+        ascending=not descending,
+    )
+    click.echo(parseur.to_json(mailboxes))
+
+
+@cli.command("get-mailbox")
+@click.argument("mailbox_id", type=int)
+def get_mailbox(mailbox_id):
+    """Get details of a mailbox."""
+    result = parseur.Mailbox.retrieve(mailbox_id)
+    click.echo(parseur.to_json(result))
+
+
+@cli.command("get-mailbox-schema")
+@click.argument("mailbox_id", type=int)
+def get_mailbox_schema(mailbox_id):
+    """Get schema of a mailbox."""
+    result = parseur.Mailbox.schema(mailbox_id)
+    click.echo(parseur.to_json(result))
+
+
+# ------------------------
+# Document commands
+# ------------------------
+
+
+@cli.command("list-documents")
+@click.argument("mailbox_id", type=int)
+@click.option(
+    "--search",
+    help="Search string (document id, name, template name, email addresses, metadata)",
+)
+@click.option(
+    "--order-by",
+    type=click.Choice([e.value for e in parseur.DocumentOrderKey]),
+    help="Order by field (name, created, processed, status)",
+)
+@click.option(
+    "--descending/--ascending",
+    default=False,
+    help="Sort descending (default is ascending)",
+)
+@click.option(
+    "--received-after",
+    type=click.DateTime(formats=["%Y-%m-%d"]),
+    help="Filter documents received after this date (YYYY-MM-DD)",
+)
+@click.option(
+    "--received-before",
+    type=click.DateTime(formats=["%Y-%m-%d"]),
+    help="Filter documents received before this date (YYYY-MM-DD)",
+)
+@click.option(
+    "--with-result",
+    is_flag=True,
+    help="Include parsed result with each document",
+)
+def list_documents(
+    mailbox_id,
+    search,
+    order_by,
+    descending,
+    received_after,
+    received_before,
+    with_result,
+):
+    """
+    List all documents in a mailbox with optional filtering, sorting, and result inclusion.
+    """
+    # Convert order_by string to enum if provided
+    order_by_enum = parseur.DocumentOrderKey(order_by) if order_by else None
+    docs = parseur.Document.list(
+        mailbox_id=mailbox_id,
+        search=search,
+        order_by=order_by_enum,
+        ascending=not descending,
+        received_after=received_after,
+        received_before=received_before,
+        with_result=with_result,
+    )
+    click.echo(parseur.to_json(docs))
+
+
+@cli.command("get-document")
+@click.argument("document_id", type=str)
+def get_document(document_id):
+    """Get details of a document."""
+    result = parseur.Document.retrieve(document_id)
+    click.echo(parseur.to_json(result))
+
+
+@cli.command("reprocess-document")
+@click.argument("document_id", type=str)
+def reprocess_document(document_id):
+    """Reprocess a document."""
+    result = parseur.Document.reprocess(document_id)
+    click.echo(parseur.to_json(result))
+
+
+@cli.command("skip-document")
+@click.argument("document_id", type=str)
+def skip_document(document_id):
+    """Skip a document."""
+    result = parseur.Document.skip(document_id)
+    click.echo(parseur.to_json(result))
+
+
+@cli.command("copy-document")
+@click.argument("document_id", type=str)
+@click.argument("target_mailbox_id", type=int)
+def copy_document(document_id, target_mailbox_id):
+    """Copy a document to another mailbox."""
+    result = parseur.Document.copy(document_id, target_mailbox_id)
+    click.echo(parseur.to_json(result))
+
+
+@cli.command("get-document-logs")
+@click.argument("document_id", type=str)
+def get_document_logs(document_id):
+    """Get logs of a document."""
+    logs = parseur.Document.logs(document_id)
+    click.echo(parseur.to_json(logs))
+
+
+@cli.command("delete-document")
+@click.argument("document_id", type=str)
+def delete_document(document_id):
+    """Delete a document."""
+    parseur.Document.delete(document_id)
+    click.echo(f"✅ Document {document_id} deleted.")
+
+
+@cli.command("upload-file")
+@click.argument("mailbox_id", type=int)
+@click.argument("file_path", type=click.Path(exists=True))
+def upload_file(mailbox_id, file_path):
+    """Upload a document file to a mailbox."""
+    result = parseur.Document.upload_file(mailbox_id, file_path)
+    click.echo(parseur.to_json(result))
+
+
+@cli.command("upload-folder")
+@click.argument("mailbox_id", type=int)
+@click.argument("folder_path", type=str)
+def upload_folder(mailbox_id, folder_path):
+    """Upload all files from a glob path."""
+    results = list(parseur.Document.upload_folder(mailbox_id, folder_path))
+    click.echo(parseur.to_json(results))
+
+
+@cli.command("upload-text")
+@click.option("--recipient", required=True, help="Mailbox email address")
+@click.option("--subject", required=True, help="Subject line for the document")
+@click.option("--sender", default=None, help="Sender email (optional)")
+@click.option("--body-html", default=None, help="HTML text content")
+@click.option("--body-plain", default=None, help="Plain text content")
+def upload_text(recipient, subject, sender, body_html, body_plain):
+    """Upload text content to a mailbox by email address."""
+    result = parseur.Document.upload_text(
+        recipient, subject, sender, body_html, body_plain
+    )
+    click.echo(parseur.to_json(result))
+
+
+# ------------------------
+# Webhook commands
+# ------------------------
+
+
+@cli.command("create-webhook")
+@click.option(
+    "--event",
+    required=True,
+    type=click.Choice([e.value for e in parseur.ParseurEvent]),
+    help="Event type to listen for",
+)
+@click.option(
+    "--target-url",
+    required=True,
+    help="The URL to receive webhook POSTs, e.g. https://api.example.com/parseur.",
+)
+@click.option(
+    "--mailbox-id",
+    type=int,
+    help="Mailbox ID (required for document events).",
+)
+@click.option(
+    "--table-field-id",
+    type=str,
+    help="Table field ID in 'PF12345' format (required for table events).",
+)
+@click.option(
+    "--header",
+    multiple=True,
+    type=str,
+    help="Custom HTTP header in 'Key:Value' format. Can be used multiple times.",
+)
+@click.option(
+    "--name",
+    type=str,
+    help="Optional name for the webhook.",
+)
+def create_webhook(event, target_url, mailbox_id, table_field_id, header, name):
+    """
+    Create a new custom webhook for your Parseur account.
+    """
+    headers = {}
+    for h in header:
+        if ":" not in h:
+            click.echo(f"❌ Invalid header format: {h}")
+            sys.exit(1)
+        key, value = h.split(":", 1)
+        headers[key.strip()] = value.strip()
+
+    event_enum = parseur.ParseurEvent(event)
+    result = parseur.Webhook.create(
+        event=event_enum,
+        target_url=target_url,
+        mailbox_id=mailbox_id,
+        table_field_id=table_field_id,
+        headers=headers or None,
+        name=name,
+    )
+    click.echo(parseur.to_json(result))
+
+
+@cli.command("get-webhook")
+@click.argument("webhook_id", type=int)
+def get_webhook(webhook_id):
+    """Get details of a webhook."""
+    result = parseur.Webhook.retrieve(webhook_id)
+    click.echo(parseur.to_json(result))
+
+
+@cli.command("delete-webhook")
+@click.argument("webhook_id", type=int)
+def delete_webhook(webhook_id):
+    """
+    Delete a registered webhook by its ID.
+
+    This command permanently removes the webhook from your Parseur account.
+    """
+    parseur.Webhook.delete(webhook_id)
+    click.echo(f"✅ Webhook {webhook_id} deleted.")
+
+
+@cli.command("enable-webhook")
+@click.argument("mailbox_id", type=int)
+@click.argument("webhook_id", type=int)
+def enable_webhook(mailbox_id, webhook_id):
+    """
+    Enable a webhook for the specified mailbox.
+
+    Activates the webhook by adding it to the mailbox.
+    """
+    result = parseur.Webhook.enable(mailbox_id, webhook_id)
+    click.echo(parseur.to_json(result))
+
+
+@cli.command("pause-webhook")
+@click.argument("mailbox_id", type=int)
+@click.argument("webhook_id", type=int)
+def pause_webhook(mailbox_id, webhook_id):
+    """
+    Pause a webhook for the specified mailbox.
+
+    Removes the webhook from the mailbox without deleting it.
+    """
+    result = parseur.Webhook.pause(mailbox_id, webhook_id)
+    click.echo(parseur.to_json(result))
+
+
+@cli.command("list-webhooks")
+def list_webhooks():
+    """List all registered webhooks."""
+    webhooks = parseur.Webhook.list()
+    click.echo(parseur.to_json(webhooks))
+
+
+if __name__ == "__main__":
+    cli()

parseur/client.py

@@ -0,0 +1,44 @@
+import logging
+from typing import Any, Dict, Generator, Optional
+from urllib.parse import urljoin
+
+import requests
+
+import parseur
+
+
+class Client:
+    @classmethod
+    def auth_headers(cls, json=True) -> Dict[str, str]:
+        if not parseur.api_key:
+            raise ValueError("API token is required. Run 'parseur init' first.")
+        headers = {"Authorization": f"Token {parseur.api_key}"}
+        if json:
+            headers["Content-Type"] = "application/json"
+        return headers
+
+    @classmethod
+    def request(cls, method: str, endpoint: str, **kwargs) -> Any:
+        url = urljoin(parseur.api_base, endpoint)
+        logging.debug(f"Request: {method} {url}")
+        headers = cls.auth_headers(json="json" in kwargs)
+        response = requests.request(method, url, headers=headers, **kwargs)
+        response.raise_for_status()
+        if response.status_code == 204:
+            return None
+        return response.json()
+
+    @classmethod
+    def paginate(
+        cls, endpoint: str, params: Optional[Dict[str, Any]] = None
+    ) -> Generator[Dict, None, None]:
+        url = urljoin(parseur.api_base, endpoint)
+        headers = cls.auth_headers()
+        while url:
+            logging.debug(f"Paginate request: {url}")
+            response = requests.get(url, headers=headers, params=params)
+            response.raise_for_status()
+            data = response.json()
+            for item in data["results"]:
+                yield item
+            url = data.get("next")

parseur/config.py

@@ -0,0 +1,32 @@
+import configparser
+import logging
+
+
+class Config:
+    def __init__(self, config_path: str):
+        self.config_path = config_path
+        self.api_key = None
+        self.api_base = None
+
+    def load(self):
+        cfg = configparser.ConfigParser()
+        if self.config_path:
+            cfg.read(self.config_path)
+        api_key = cfg.get("parseur", "api_key")
+        api_base = cfg.get("parseur", "api_base")
+        self.api_key = api_key
+        self.api_base = api_base
+        return cfg
+
+    def save(self):
+        if not self.config_path:
+            raise ValueError("Config path must be set before saving.")
+        cfg = configparser.ConfigParser()
+        cfg.read(self.config_path)
+        if not cfg.has_section("parseur"):
+            cfg.add_section("parseur")
+        cfg.set("parseur", "api_key", self.api_key)
+        cfg.set("parseur", "api_base", self.api_base)
+        with open(self.config_path, "w") as f:
+            cfg.write(f)
+        logging.info(f"Config saved to {self.config_path}")

parseur/decorator.py

@@ -0,0 +1,49 @@
+import functools
+import logging
+import time
+from typing import Any, Callable, Iterable
+
+
+def rate_limited_batch(batch_size: int = 5, max_per_second: int = 5):
+    """
+    Decorator for a batch-processing function that takes a list of items and yields results.
+    Applies rate limiting: max N calls per second, B items per batch.
+    """
+    assert batch_size > 0 and max_per_second > 0
+
+    def decorator(func: Callable[..., Iterable[Any]]):
+        @functools.wraps(func)
+        def wrapper(cls, items: Iterable[Any], *args, **kwargs) -> Iterable[Any]:
+            batch = []
+            start_time = None
+
+            for item in items:
+                logging.info(f"Processing item: {item}")
+                batch.append(item)
+
+                if len(batch) >= batch_size:
+                    if start_time:
+                        elapsed = time.time() - start_time
+                        sleep_time = max(0, 1.0 - elapsed)
+                        if sleep_time > 0:
+                            time.sleep(sleep_time)
+
+                    start_time = time.time()
+                    for result in func(cls, batch, *args, **kwargs):
+                        yield result
+                    batch = []
+
+            # Remaining items
+            if batch:
+                if start_time:
+                    elapsed = time.time() - start_time
+                    sleep_time = max(0, 1.0 - elapsed)
+                    if sleep_time > 0:
+                        time.sleep(sleep_time)
+
+                for result in func(cls, batch, *args, **kwargs):
+                    yield result
+
+        return wrapper
+
+    return decorator

parseur/document.py

@@ -0,0 +1,212 @@
+from datetime import datetime, timezone
+from enum import Enum
+from glob import iglob
+import logging
+from pathlib import Path
+from typing import Dict, Iterable, List, Optional
+
+from parseur.client import Client
+from parseur.decorator import rate_limited_batch
+from parseur.schemas.document import DocumentLogSchema, DocumentSchema
+
+
+class DocumentOrderKey(str, Enum):
+    """
+    Enumeration of supported document sorting keys.
+
+    Used with the `order_by` parameter to specify sorting in list_documents and yield_documents.
+
+    Members:
+
+    - `NAME`: Sort by document name.
+    - `CREATED`: Sort by created/received date.
+    - `PROCESSED`: Sort by processed date.
+    - `STATUS`: Sort by document status.
+    """
+
+    NAME = "name"
+    CREATED = "created"
+    PROCESSED = "processed"
+    STATUS = "status"
+
+
+class Document:
+    """Document resource providing class-based API access."""
+
+    @classmethod
+    def from_response(cls, data: Dict) -> Dict:
+        """Validate and deserialize a single document dict."""
+        return DocumentSchema().load(data)
+
+    @classmethod
+    def log_from_response(cls, data: Dict) -> Dict:
+        """Validate and deserialize a single document log dict."""
+        return DocumentLogSchema().load(data)
+
+    @classmethod
+    def iter(
+        cls,
+        mailbox_id: int,
+        *,
+        search: Optional[str] = None,
+        order_by: Optional[DocumentOrderKey] = None,
+        ascending: bool = True,
+        received_after: Optional[datetime] = None,
+        received_before: Optional[datetime] = None,
+        with_result: bool = False,
+    ) -> Iterable[Dict]:
+        """
+        Yield all documents in a mailbox with pagination and filtering.
+
+        :param mailbox_id: The mailbox ID to retrieve documents from.
+        :param str search: Search string to filter documents.
+            The search query parameter searches the following properties:
+
+            - document id (exact match)
+            - document name
+            - template name
+            - from, to, cc, and bcc email addresses
+            - document metadata header
+
+        :param DocumentOrderKey order_by: Enum value specifying the sorting field.
+        :param bool ascending: Whether to sort in ascending order (True) or descending order (False).
+        :param datetime.datetime received_after: Filter for documents received after this date (converted to UTC YYYY-MM-DD).
+        :param datetime.datetime received_before: Filter for documents received before this date (converted to UTC YYYY-MM-DD).
+        :param bool with_result: Whether to include the parsed result in the returned documents.
+        :yield dict: Each yielded dictionary represents a document.
+        """
+        params = {}
+
+        if search:
+            params["search"] = search
+
+        if order_by:
+            prefix = "" if ascending else "-"
+            params["ordering"] = f"{prefix}{order_by.value}"
+
+        if received_after:
+            utc_date = received_after.astimezone(timezone.utc).strftime("%Y-%m-%d")
+            params["received_after"] = utc_date
+        if received_before:
+            utc_date = received_before.astimezone(timezone.utc).strftime("%Y-%m-%d")
+            params["received_before"] = utc_date
+
+        if received_after or received_before:
+            params["tz"] = "UTC"
+
+        if with_result:
+            params["with_result"] = "true"
+
+        for raw in Client.paginate(f"/parser/{mailbox_id}/document_set", params=params):
+            yield cls.from_response(raw)
+
+    @classmethod
+    def list(
+        cls,
+        mailbox_id: int,
+        *,
+        search: Optional[str] = None,
+        order_by: Optional[DocumentOrderKey] = None,
+        ascending: bool = True,
+        received_after: Optional[datetime] = None,
+        received_before: Optional[datetime] = None,
+        with_result: bool = False,
+    ) -> List[Dict]:
+        return list(
+            cls.iter(
+                mailbox_id,
+                search=search,
+                order_by=order_by,
+                ascending=ascending,
+                received_after=received_after,
+                received_before=received_before,
+                with_result=with_result,
+            )
+        )
+
+    @classmethod
+    def retrieve(cls, document_id: str) -> Dict:
+        """Retrieve document details, deserialized."""
+        raw = Client.request("GET", f"/document/{document_id}")
+        return cls.from_response(raw)
+
+    @classmethod
+    def reprocess(cls, document_id: str) -> Dict:
+        raw = Client.request("POST", f"/document/{document_id}/process")
+        return cls.from_response(raw)
+
+    @classmethod
+    def skip(cls, document_id: str) -> Dict:
+        raw = Client.request("POST", f"/document/{document_id}/skip")
+        return cls.from_response(raw)
+
+    @classmethod
+    def copy(cls, document_id: str, target_mailbox_id: int) -> Dict:
+        raw = Client.request(
+            "POST", f"/document/{document_id}/copy/{target_mailbox_id}"
+        )
+        return cls.from_response(raw)
+
+    @classmethod
+    def logs(cls, document_id: str) -> List[Dict]:
+        logs = []
+        for raw in Client.paginate(f"/document/{document_id}/log_set"):
+            logs.append(cls.log_from_response(raw))
+        return logs
+
+    @classmethod
+    def delete(cls, document_id: str) -> bool:
+        Client.request("DELETE", f"/document/{document_id}")
+        logging.info(f"Deleted document ID: {document_id}")
+        return True
+
+    @classmethod
+    def upload_file(cls, mailbox_id: int, file_path: str) -> Dict:
+        with open(file_path, "rb") as file:
+            files = {"file": file}
+            response = Client.request(
+                "POST", f"/parser/{mailbox_id}/upload", files=files
+            )
+            if response.status_code >= 400:
+                logging.error(f"API Error {response.status_code}: {response.text}")
+                response.raise_for_status()
+            return response.json()
+
+    @classmethod
+    @rate_limited_batch()
+    def batch_upload_files(
+        cls, file_paths: List[str], mailbox_id: int
+    ) -> Iterable[Dict]:
+        for file_path in file_paths:
+            try:
+                yield cls.upload_file(mailbox_id, file_path)
+            except Exception as e:
+                yield {"file": file_path, "error": str(e)}
+
+    @classmethod
+    def upload_folder(cls, mailbox_id: int, folder_path: str) -> Iterable[Dict]:
+        paths = (
+            str(p) for p in iglob(folder_path, recursive=True) if Path(p).is_file()
+        )
+        return cls.batch_upload_files(paths, mailbox_id)
+
+    @classmethod
+    def upload_text(
+        cls,
+        recipient: str,
+        subject: str,
+        sender: Optional[str] = None,
+        body_html: Optional[str] = None,
+        body_plain: Optional[str] = None,
+    ) -> Dict:
+        data = {"recipient": recipient, "subject": subject}
+        if sender:
+            data["from"] = sender
+        if body_html:
+            data["body_html"] = body_html
+        if body_plain:
+            data["body_plain"] = body_plain
+        logging.info(
+            f"Uploading text to Parseur: recipient={recipient}, subject={subject}"
+        )
+        return Client.request("POST", "/email", json=data)

parseur/event.py

@@ -0,0 +1,28 @@
+from enum import Enum
+
+
+class ParseurEvent(str, Enum):
+    """
+    Enumeration of supported Parseur webhook event types.
+
+    Use these values when registering webhooks to specify which event to listen for.
+
+    Members:
+
+    - `DOCUMENT_PROCESSED`: Document processed successfully.
+    - `DOCUMENT_PROCESSED_FLATTENED`: Document processed as flat data.
+    - `DOCUMENT_TEMPLATE_NEEDED`: Document processing failed (template needed).
+    - `DOCUMENT_EXPORT_FAILED`: Export of the document failed.
+    - `TABLE_PROCESSED`: A table field row was processed.
+    - `TABLE_PROCESSED_FLATTENED`: A table field row (flattened) was processed.
+    """
+
+    DOCUMENT_PROCESSED = "document.processed"
+    DOCUMENT_PROCESSED_FLATTENED = "document.processed.flattened"
+    DOCUMENT_TEMPLATE_NEEDED = "document.template_needed"
+    DOCUMENT_EXPORT_FAILED = "document.export_failed"
+    TABLE_PROCESSED = "table.processed"
+    TABLE_PROCESSED_FLATTENED = "table.processed.flattened"
+
+    def is_table_event(self) -> bool:
+        return self.value.startswith("table")

parseur/mailbox.py

@@ -0,0 +1,77 @@
+from enum import Enum
+from typing import Any, Dict, Iterable, List, Optional
+
+from parseur.client import Client
+from parseur.schemas.mailbox import MailboxSchema
+from parseur.utils import resolve_absolute_urls
+
+
+class MailboxOrderKey(str, Enum):
+    """
+    Enumeration of supported mailbox sorting keys.
+
+    Used with the `order_by` parameter to specify sorting in Mailbox.list() and Mailbox.iter().
+    """
+
+    NAME = "name"
+    DOCUMENT_COUNT = "document_count"
+    TEMPLATE_COUNT = "template_count"
+    PARSEDOK_COUNT = "PARSEDOK_count"
+    PARSEDKO_COUNT = "PARSEDKO_count"
+    QUOTAEXC_COUNT = "QUOTAEXC_count"
+    EXPORTKO_COUNT = "EXPORTKO_count"
+
+
+class Mailbox:
+
+    @classmethod
+    def from_response(cls, data: Dict) -> Dict:
+        """
+        Deserialize a single mailbox API response.
+
+        :param data: Raw API response dictionary.
+        :return: Validated and transformed mailbox dictionary.
+        """
+        return resolve_absolute_urls(MailboxSchema().load(data))
+
+    @classmethod
+    def iter(
+        cls,
+        *,
+        search: Optional[str] = None,
+        order_by: Optional[MailboxOrderKey] = None,
+        ascending: bool = True,
+    ) -> Iterable[Dict]:
+        """
+        Yield all mailboxes with pagination and optional filtering or sorting.
+        """
+        params = {}
+        if search:
+            params["search"] = search
+        if order_by:
+            prefix = "" if ascending else "-"
+            params["ordering"] = f"{prefix}{order_by.value}"
+        for raw in Client.paginate("/parser", params=params):
+            yield cls.from_response(raw)
+
+    @classmethod
+    def list(
+        cls,
+        *,
+        search: Optional[str] = None,
+        order_by: Optional[MailboxOrderKey] = None,
+        ascending: bool = True,
+    ) -> List[Dict[str, Any]]:
+        """Retrieve all mailboxes as a list."""
+        return list(cls.iter(search=search, order_by=order_by, ascending=ascending))
+
+    @classmethod
+    def retrieve(cls, mailbox_id: int) -> Dict[str, Any]:
+        """Retrieve a single mailbox by ID."""
+        raw = Client.request("GET", f"/parser/{mailbox_id}")
+        return cls.from_response(raw)
+
+    @classmethod
+    def schema(cls, mailbox_id: int) -> Dict[str, Any]:
+        """Get the schema for a mailbox."""
+        return Client.request("GET", f"/parser/{mailbox_id}/schema")

parseur/utils.py

@@ -0,0 +1,52 @@
+from datetime import date, datetime
+import json
+from urllib.parse import urljoin
+
+import parseur
+
+ABSOLUTE_URL_FIELDS = {"csv_download", "json_download", "xls_download"}
+
+
+def resolve_absolute_urls(obj):
+    if isinstance(obj, dict):
+        for key in obj:
+            if key in ABSOLUTE_URL_FIELDS and obj[key]:
+                obj[key] = urljoin(parseur.api_base, obj[key])
+            else:
+                obj[key] = resolve_absolute_urls(obj[key])
+    elif isinstance(obj, list):
+        return [resolve_absolute_urls(item) for item in obj]
+    return obj
+
+
+class ISODateJSONEncoder(json.JSONEncoder):
+    """
+    JSON Encoder that converts datetime and date objects to ISO 8601 strings.
+    """
+
+    def default(self, obj):
+        if isinstance(obj, (datetime, date)):
+            return obj.isoformat()
+        return super().default(obj)
+
+
+def to_json(data, indent=2, sort_keys=True, ensure_ascii=False):
+    """
+    Serialize a Python object to a JSON-formatted string with ISO datetime support.
+
+    This function uses the custom ISODateJSONEncoder to automatically
+    convert datetime.datetime objects to ISO 8601 strings.
+
+    :param data: The data to serialize (dict, list, etc.).
+    :param indent: Number of spaces to indent in the output JSON. Default is 2.
+    :param sort_keys: Whether to sort the dictionary keys in the output. Default is True.
+    :param ensure_ascii: Whether to escape non-ASCII characters. Default is False.
+    :return: A JSON-formatted string.
+    """
+    return json.dumps(
+        data,
+        indent=indent,
+        sort_keys=sort_keys,
+        ensure_ascii=ensure_ascii,
+        cls=ISODateJSONEncoder,
+    )

parseur/webhook.py

@@ -0,0 +1,122 @@
+import logging
+from typing import Any, Dict, Iterable, List, Optional
+
+from parseur.event import ParseurEvent
+from parseur.schemas.webhook import WebhookSchema
+from parseur.client import Client
+from parseur.mailbox import Mailbox
+
+
+class Webhook:
+
+    @classmethod
+    def from_response(cls, data: Dict) -> Dict:
+        """
+        Deserialize a webhook API response.
+
+        :param data: Raw API response dictionary.
+        :return: Deserialized webhook dictionary.
+        """
+        return WebhookSchema().load(data)
+
+    @classmethod
+    def create(
+        cls,
+        event: ParseurEvent,
+        target_url: str,
+        mailbox_id: Optional[int] = None,
+        table_field_id: Optional[str] = None,
+        headers: Optional[Dict[str, str]] = None,
+        name: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """
+        Create a new custom webhook for Parseur.
+
+        :param event: Webhook event type (document or table event).
+        :param target_url: The URL to send webhook POSTs to.
+        :param mailbox_id: Mailbox ID (required for document events).
+        :param table_field_id: Table field ID (required for table events, e.g. "PF12345").
+        :param headers: Optional custom HTTP headers.
+        :param name: Optional custom name for the webhook.
+        :return: The created webhook object as a dictionary.
+        """
+        body = {
+            "event": event.value,
+            "target": target_url,
+            "category": "CUSTOM",
+        }
+
+        if name:
+            body["name"] = name
+        if headers:
+            body["headers"] = headers
+
+        if event.is_table_event():
+            if not table_field_id:
+                raise ValueError("table_field_id is required for table events")
+            body["parser_field"] = table_field_id
+        else:
+            if not mailbox_id:
+                raise ValueError("mailbox_id is required for document events")
+            body["parser"] = mailbox_id
+
+        raw = Client.request("POST", "/webhook", json=body)
+        return cls.from_response(raw)
+
+    @classmethod
+    def retrieve(cls, webhook_id: int) -> bool:
+        """
+        Retrieve a webhook from the account.
+
+        :param webhook_id: ID of the webhook to delete.
+        :return: The updated mailbox object as a dictionary.
+        """
+        raw = Client.request("GET", f"/webhook/{webhook_id}")
+        return cls.from_response(raw)
+
+    @classmethod
+    def delete(cls, webhook_id: int) -> bool:
+        """
+        Delete a webhook from the account.
+
+        :param webhook_id: ID of the webhook to delete.
+        :return: True if deletion was successful.
+        """
+        Client.request("DELETE", f"/webhook/{webhook_id}")
+        logging.info(f"Deleted webhook ID: {webhook_id}")
+        return True
+
+    @classmethod
+    def enable(cls, mailbox_id: int, webhook_id: int) -> Dict[str, Any]:
+        """
+        Enable an existing webhook for a given mailbox.
+
+        :param mailbox_id: ID of the mailbox.
+        :param webhook_id: ID of the webhook to enable.
+        :return: The updated mailbox object as a dictionary.
+        """
+        raw = Client.request("POST", f"/parser/{mailbox_id}/webhook_set/{webhook_id}")
+        return Mailbox.from_response(raw)
+
+    @classmethod
+    def pause(cls, mailbox_id: int, webhook_id: int) -> Dict[str, Any]:
+        """
+        Pause (disable) an existing webhook for a given mailbox.
+
+        :param mailbox_id: ID of the mailbox.
+        :param webhook_id: ID of the webhook to pause.
+        :return: The updated mailbox object as a dictionary.
+        """
+        raw = Client.request("DELETE", f"/parser/{mailbox_id}/webhook_set/{webhook_id}")
+        return Mailbox.from_response(raw)
+
+    @classmethod
+    def list(cls) -> List[Dict[str, Any]]:
+        """Retrieve all webhooks as a list."""
+        return list(cls.iter())
+
+    @classmethod
+    def iter(cls) -> Iterable[Dict[str, Any]]:
+        """Yield all webhooks registered on the account."""
+        for raw in Client.request("GET", "/webhook"):
+            yield cls.from_response(raw)

parseur_py-0.0.1.dist-info/METADATA

@@ -0,0 +1,242 @@
+Metadata-Version: 2.4
+Name: parseur-py
+Version: 0.0.1
+Summary: A Python client for the Parseur.com API to manage mailboxes, documents, uploads, and listen for new parsing events.
+Author-email: Parseur Team <admin@parseur.com>
+Project-URL: Homepage, https://github.com/parseur/parseur-py
+Project-URL: Repository, https://github.com/parseur/parseur-py
+Project-URL: Issues, https://github.com/parseur/parseur-py/issues
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.2.1
+Requires-Dist: requests>=2.31.0
+Requires-Dist: marshmallow>=4.0.0
+Dynamic: license-file
+
+# 🤖🧙parseur-py
+
+**parseur-py** is a modern Python client for the [Parseur](https://parseur.com) API. It lets you **manage mailboxes, documents, uploads, and webhooks** programmatically or from the command line.
+
+Built to help you automate document parsing at scale, parseur-py makes integrating with Parseur fast, easy, and Pythonic.
+
+[![GitHub Repo](https://img.shields.io/badge/GitHub-parseur--py-blue?logo=github)](https://github.com/parseur/parseur-py)
+[![PyPI version](https://badge.fury.io/py/parseur-py.svg)](https://badge.fury.io/py/parseur-py)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## ✨ Features
+
+✅ List, search, and sort mailboxes  
+✅ Get mailbox details and schema  
+✅ List, search, filter, and sort documents  
+✅ Upload documents by file or email content  
+✅ Reprocess, skip, copy, or delete documents  
+✅ Manage custom webhooks for real-time events  
+✅ Fully-featured **Command Line Interface (CLI)**
+
+---
+
+## 🚀 Quick Start
+
+### Install the package
+
+```bash
+pip install parseur-py
+```
+
+### Install the package from source
+
+```bash
+pip install -e .
+```
+
+### Build documentation
+
+```bash
+pip install -r requirements-doc.txt
+cd docs
+make html
+```
+
+---
+
+### Initialize your configuration
+
+Store your Parseur API credentials securely:
+
+```bash
+parseur init --api-key YOUR_PARSEUR_API_KEY
+```
+
+Your config is saved (by default) in:
+
+```
+~/.parseur.conf
+```
+
+---
+
+### Example usage
+
+List all your mailboxes:
+
+```bash
+parseur list-mailboxes
+```
+
+List documents in a mailbox:
+
+```bash
+parseur list-documents 12345
+```
+
+Upload a file to a mailbox:
+
+```bash
+parseur upload-file 12345 ./path/to/document.pdf
+```
+
+Register a custom webhook:
+
+```bash
+parseur create-webhook --event document.processed --target-url https://yourserver.com/webhook --mailbox-id 12345
+```
+
+---
+
+## 📜 CLI Commands
+
+Run:
+
+```bash
+parseur --help
+```
+
+for a full list of available commands.
+
+### Highlights
+
+- **init**: Set your API token and (optional) base URL  
+- **list-mailboxes**: Search and sort mailboxes  
+- **get-mailbox**: Fetch a mailbox by ID  
+- **get-mailbox-schema**: Get the mailbox parsing schema  
+- **list-documents**: Advanced document search, filtering, sorting  
+- **get-document**: Fetch document details  
+- **reprocess-document / skip-document / delete-document**: Document lifecycle operations  
+- **upload-file / upload-text**: Upload new documents  
+- **create-webhook / get-webhook / list-webhooks / delete-webhook**: Create, get, list, and delete custom webhook integrations.
+- **enable-webhook / pause-webhook**: Activate or pause a webhook for a specific mailbox.
+
+---
+
+## 🔎 Advanced Search & Filtering
+
+**Mailbox listing supports:**
+
+- **Search** by name or email prefix
+- **Sort** by:
+  - name
+  - document_count
+  - template_count
+  - PARSEDOK_count (processed)
+  - PARSEDKO_count (failed)
+  - QUOTAEXC_count (quota exceeded)
+  - EXPORTKO_count (export failed)
+
+**Document listing supports:**
+
+- **Search** in:
+  - document ID
+  - document name
+  - template name
+  - email addresses (from, to, cc, bcc)
+  - document metadata header
+- **Sort** by:
+  - name
+  - created (received date)
+  - processed date
+  - status
+- **Filter** by:
+  - received_after / received_before dates
+- **Include** parsed result in response
+
+---
+
+## ⚡ Webhooks Support
+
+Easily register custom webhooks for events like:
+
+- `document.processed`
+- `document.processed.flattened`
+- `document.template_needed`
+- `document.export_failed`
+- `table.processed`
+- `table.processed.flattened`
+
+Your webhook endpoint will receive POST notifications with Parseur payloads, enabling real-time integrations with your systems.
+
+---
+
+## 🛠️ Configuration
+
+Your API token and settings are stored in a simple INI file:
+
+```
+[parseur]
+api_token = YOUR_API_KEY
+base_url = https://api.parseur.com
+```
+
+You can customize the path by setting \`--config-path\` in your calls if needed.
+
+---
+
+## 🐍 Python Client Usage
+
+Beyond the CLI, **parseur-py** is a standard Python library. Example:
+
+```python
+import parseur
+
+parseur.api_key = "YOUR_API_KEY"
+
+for mailbox in parseur.Mailbox.list():
+    print(mailbox["name"])
+```
+
+---
+
+## 📖 Documentation
+
+- [Parseur Official API Docs](https://help.parseur.com/en/articles/3566128-use-parseur-document-parsing-api)
+- This package mirrors Parseur’s REST API, adding pagination handling, schema support, and convenient CLI commands.
+
+---
+
+## 💼 License
+
+MIT License
+
+---
+
+## 🤝 Contributing
+
+We welcome contributions! Please:
+
+1. Fork the repo
+2. Create your feature branch (`git checkout -b feature/foo`)
+3. Commit your changes (`git commit -am 'Add foo'`)
+4. Push to the branch (`git push origin feature/foo`)
+5. Open a pull request
+
+---
+
+## ✨ Credits
+
+Developed with ❤️ by the [Parseur](https://parseur.com) team.
+
+---
+
+*Parseur is the easiest way to automatically extract data from emails and documents. Stop copy-pasting data and automate your workflows!*

parseur_py-0.0.1.dist-info/RECORD

@@ -0,0 +1,16 @@
+parseur/__init__.py,sha256=urneWGucdS4jmwh-tb1j1UAnNT4FhKnsTb6NOuVDxEc,717
+parseur/cli.py,sha256=dozg0EOLieG9bCwq2rujcuoW6inuM-MDEPAxQwxGmsQ,9707
+parseur/client.py,sha256=eGFYl_pthbulehh_Csk7sOqOcvf9_HfbJstE0qzKHrE,1497
+parseur/config.py,sha256=qI5HgPH2yg33x6y7sTLX6UUm-LZTfn4ImpR483K4Gxg,1023
+parseur/decorator.py,sha256=yC9D5U6aLj4rTuQw3AUS0_cz78jEGPVvULQi7sWFlOo,1634
+parseur/document.py,sha256=mTZibUkIFlQ85TQZgwDW6XuTONWtxjRSorejhOukyAE,7232
+parseur/event.py,sha256=tNCS70MVuoWOZ3g6BjwnE-4C4iGpK3ts7fCK6-N-FQg,1053
+parseur/mailbox.py,sha256=YmA5bcqm3laccBGlsIgzReF4DSQe4FR6e56PyApY9Nw,2359
+parseur/utils.py,sha256=Mx7az0A2XbCag1yM8dhF_2jREsDxgjZRxBDdZU5RbdY,1658
+parseur/webhook.py,sha256=Krq-xpS6a3aZPs_pf10wTy1INfXGd8dKJK6zb3rLsAk,4088
+parseur_py-0.0.1.dist-info/licenses/LICENSE,sha256=wlaTLxAYcgFP2EDvy5Dvrq5aqKOdh7k16AzS1r2vPZU,1064
+parseur_py-0.0.1.dist-info/METADATA,sha256=ZZ9hdCoTWgp8bPFy6e859Ob5l8FyMU5B3hyFVCjFQRo,5605
+parseur_py-0.0.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+parseur_py-0.0.1.dist-info/entry_points.txt,sha256=gcCC05O_4YfWK76ZXNX7s7ChwgriVVSaQ06e1R6AFHU,44
+parseur_py-0.0.1.dist-info/top_level.txt,sha256=yvljW9vjQJA24AGSxgzlUjx2jfkVvzdEzmfF_fD322E,8
+parseur_py-0.0.1.dist-info/RECORD,,

parseur_py-0.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

parseur_py-0.0.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+parseur = parseur.cli:cli

parseur_py-0.0.1.dist-info/licenses/LICENSE

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

parseur_py-0.0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+parseur