exportflow 1.0.0__tar.gz

exportflow-1.0.0/.gitignore

@@ -0,0 +1,145 @@
+# ExportFlow — .gitignore
+#
+# This is the first commit in the repository, deliberately. Everything after it
+# is safe by construction; doing it second would mean the first commit is the
+# one that has to be audited.
+#
+# Banned from version control by standing rule (Foundation 1.6):
+#   secrets, databases, build artifacts, virtualenvs.
+
+# --- Secrets -----------------------------------------------------------------
+# .env.example is the one exception: the README's clean-machine bootstrap
+# depends on it, so it must be committed.
+.env
+.env.*
+!.env.example
+.envrc
+*.pem
+*.key
+*.p12
+*.pfx
+id_rsa*
+credentials.json
+service-account*.json
+
+# --- Databases ---------------------------------------------------------------
+*.db
+*.sqlite
+*.sqlite3
+*.sqlite3-journal
+*.dump
+*.sql.gz
+pgdata/
+
+# --- Python ------------------------------------------------------------------
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+eggs/
+.eggs/
+sdist/
+wheels/
+share/python-wheels/
+*.egg-info/
+*.egg
+MANIFEST
+
+# --- Virtualenvs -------------------------------------------------------------
+.venv/
+venv/
+ENV/
+env/
+.python-version.local
+
+.ocr-check/
+
+# --- Tooling caches ----------------------------------------------------------
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.hypothesis/
+.import_linter_cache/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+.tox/
+.nox/
+
+# --- Editors and OS ----------------------------------------------------------
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+Thumbs.db
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# --- Real customer documents -------------------------------------------------
+# UNREDACTED ORIGINALS. These are real commercial documents: consignee names,
+# bank references, cargo values. They must never be committed.
+#
+# The brief described this directory as outside the repository. It is not — it
+# sits at the repository root, and the root-anchored /*.pdf rule below does not
+# reach into it, so one `git add -A` would have committed the lot.
+#
+# The redacted corpus lives at api/tests/fixtures/documents/ and is built from
+# these; the originals stay here and stay ignored.
+/sample_docs/
+
+# --- Source and rendered documents -------------------------------------------
+# docs/reference/ holds the binaries the written documentation was produced
+# from or rendered to: the source workbooks, and the PDF/zip renderings of
+# docs/*.md. They are inputs and artefacts, not sources, and they are large.
+#
+# NOT a blanket `*.pdf`: the Phase 3 golden corpus at
+# api/tests/fixtures/documents/ is PDFs of real Bills of Lading, and a
+# repository-wide rule would make the first one invisible to `git status`.
+# Foundation 10.3 rates that corpus above any coverage number.
+/docs/reference/
+/*.pdf
+/*.zip
+
+# --- Node (web/ and mobile/, from Phase 4) -----------------------------------
+node_modules/
+.next/
+.expo/
+*.tsbuildinfo
+
+# Manually acquired source documents. Real regulatory PDFs with real provenance,
+# kept out of git deliberately: they are large, they are republished by their
+# authorities, and their hashes are recorded in regulatory_document instead.
+ops/sources/
+
+# The pitch deck and its screenshots. 188 MB of .pptx, .pdf and full-page PNGs,
+# regenerated from the running product rather than authored here, and git keeps
+# every version of a binary for ever. They live on disk beside the docs that
+# describe them; nothing in the build reads them.
+/docs/pitch/
+.vercel
+.env*
+
+# App Store Connect API keys
+*.p8
+
+# Local agent worktrees and session state
+.claude/
+
+# Generated by `make ai-golden` (synthetic, never committed)
+ops/eval/ai_golden/cases/
+ops/eval/ai_golden/manifest.json
+ops/eval/ai-eval-report.json
+
+# SDK build output
+sdks/python/dist/
+sdks/typescript/dist/
+sdks/typescript/node_modules/

exportflow-1.0.0/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to the ExportFlow Python SDK. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the SDK follows
+[Semantic Versioning](https://semver.org/).
+
+## [1.0.0] - 2026-11-11
+
+First release. Speaks version 1 of the ExportFlow API (`/public/v1`).
+
+### Added
+- `ExportFlow` client with `shipments`, `documents`, `records`,
+  `verifications`, `usage` and `webhook_endpoints`.
+- `documents.wait` and `verifications.wait` polling helpers.
+- Automatic retries with backoff that reuse the request's idempotency key.
+- Typed errors carrying the API's `code`, HTTP status and request id.
+- `exportflow.webhooks.construct_event` and `verify` for signed deliveries.
+- A check of the API's major version on every response.
+- Detection of a file's media type from its content.
+
+### Compatibility
+- Python 3.9+. API version 1.x.

exportflow-1.0.0/PKG-INFO

@@ -0,0 +1,222 @@
+Metadata-Version: 2.5
+Name: exportflow
+Version: 1.0.0
+Summary: The official Python SDK for the ExportFlow document processing and verification API
+Project-URL: Documentation, https://exportflow.app/developers
+Project-URL: Changelog, https://exportflow.app/developers/changelog
+Author: MeerTech Ltd
+License: Proprietary
+Keywords: documents,erp,exportflow,ocr,trade,verification
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx<1,>=0.25
+Description-Content-Type: text/markdown
+
+# ExportFlow Python SDK
+
+The official Python client for the ExportFlow API: upload trade documents from
+your own software, have them classified and read, confirm what they say, and
+verify them against each other.
+
+```bash
+pip install exportflow
+```
+
+Python 3.9 or later. The only dependency is `httpx`.
+
+## Quick start
+
+```python
+from exportflow import ExportFlow
+
+client = ExportFlow(api_key="exfk_test_...")   # or set EXPORTFLOW_API_KEY
+
+# 1. Upload. The document is scanned, stored and queued for processing.
+document = client.documents.upload(file="bill_of_lading.pdf")
+
+# 2. Wait for processing (or use a webhook; see below).
+document = client.documents.wait(document.id)
+print(document.status, document.document_type)        # processed bill_of_lading
+
+# 3. Read what was extracted.
+extraction = client.documents.extraction(document.id)
+print(extraction.as_dict())                           # {"bl_number": "MEDU7741203", ...}
+
+# 4. Confirm what the documents say, then verify the shipment.
+client.records.confirm(document.shipment_id, {"port_of_discharge": "NHAVA SHEVA"})
+verification = client.verifications.create(document.shipment_id)
+verification = client.verifications.wait(verification.id)
+for finding in verification.findings:
+    print(finding.severity, finding.message)
+```
+
+A key that begins `exfk_test_` works in the **sandbox**: the same pipeline,
+separate data, never charged. A key that begins `exfk_live_` is **production**.
+Create both in the developer console.
+
+## How ExportFlow models documents
+
+A **shipment** is a set of documents that travel together: a bill of lading, a
+commercial invoice, a packing list, certificates. Documents are uploaded to a
+shipment, each is **processed** (classified, then its fields extracted), and
+the shipment is **verified** by checking the documents against each other and
+against the published rule set.
+
+`client.documents.upload(file=...)` with no `shipment_id` creates a shipment
+for the document. To group several documents, create the shipment first:
+
+```python
+shipment = client.shipments.create(reference="PO-7741", origin_country="NG",
+                                   destination_country="IN")
+for path in ("bl.pdf", "invoice.pdf", "packing_list.pdf"):
+    client.documents.upload(file=path, shipment_id=shipment.id)
+```
+
+### Why you confirm before you verify
+
+Verification refuses to start (`ConflictError`, code `not_confirmed`) until the
+shipment's record has been confirmed. This is deliberate. If a field was
+misread, every finding computed from it would be wrong, in both directions.
+Show your user what was read (`client.records.get(shipment_id)`), let them
+confirm or correct it, and send that with `client.records.confirm(...)`.
+Confirm what the document *says*, not what it should say: verification is what
+finds the error.
+
+## Webhooks
+
+Polling works; webhooks are better. Register an endpoint once:
+
+```python
+endpoint = client.webhook_endpoints.create(
+    "https://erp.example.com/hooks/exportflow",
+    event_types=["document.processing.completed", "verification.completed"],
+)
+print(endpoint.signing_secret)   # whsec_...  store this
+```
+
+Verify every delivery before trusting it:
+
+```python
+from exportflow import webhooks, SignatureVerificationError
+
+def handle(request):
+    try:
+        event = webhooks.construct_event(
+            payload=request.body,                               # raw bytes
+            signature=request.headers["ExportFlow-Signature"],
+            secret=WEBHOOK_SECRET,
+        )
+    except SignatureVerificationError:
+        return 400
+    if already_handled(event.id):          # deliveries are at-least-once
+        return 200
+    if event.type == "document.processing.completed":
+        document_id = event.data["document"]["id"]
+        ...
+    return 200
+```
+
+Answer with any `2xx` within 10 seconds. Anything else is retried with
+increasing delays for about two and a half hours. An event carries identifiers
+and statuses, never document content: fetch the resource to read it.
+
+| Event | When |
+|---|---|
+| `document.uploaded` | A document was accepted, scanned and stored |
+| `document.processing.started` | Classification began |
+| `document.processing.completed` | The document was classified and read |
+| `document.processing.failed` | Processing stopped; `GET` the document for why |
+| `verification.completed` | A verification finished; fetch it for the findings |
+| `verification.failed` | A verification could not run |
+| `billing.invoice.generated` | An invoice was issued to your organisation |
+
+## Errors
+
+Every error is an `exportflow.ExportFlowError`. One returned by the API is an
+`APIError` with a stable `code`, the HTTP `status_code` and a `request_id` to
+quote to support. Branch on the type or the code, never on the message.
+
+```python
+import exportflow
+
+try:
+    client.verifications.create(shipment_id)
+except exportflow.ConflictError as error:
+    if error.code == "not_confirmed":
+        ...                                   # ask the user to confirm the record
+except exportflow.QuotaExceededError:
+    ...                                       # the month's allowance is used up
+except exportflow.RateLimitError as error:
+    time.sleep(error.retry_after or 5)
+except exportflow.APIConnectionError:
+    ...                                       # safe to retry later
+```
+
+| Exception | HTTP | Meaning |
+|---|---|---|
+| `AuthenticationError` | 401 | Key missing, wrong, revoked or expired |
+| `PermissionDeniedError` | 403 | Missing scope, suspended account, network not allowed |
+| `NotFoundError` | 404 | No such resource in this organisation and environment |
+| `ConflictError` | 409 | Not possible in the current state (e.g. `not_confirmed`) |
+| `InvalidRequestError` | 400, 422 | The request is wrong; do not retry |
+| `RateLimitError` | 429 | Slow down; see `retry_after` |
+| `QuotaExceededError` | 429 | Allowance or spending limit reached for the period |
+| `SDKVersionUnsupportedError` | 426 | Upgrade this SDK |
+| `ServerError` | 5xx | ExportFlow's fault; retried automatically |
+| `APIConnectionError`, `APITimeoutError` | none | The API could not be reached |
+
+## Retries and idempotency
+
+The client retries connection failures, timeouts, `429 rate_limited` and `5xx`
+up to `max_retries` times (default 2), with backoff, honouring `Retry-After`.
+
+Every request that changes something carries an `Idempotency-Key`, and a retry
+sends the *same* key and the *same* body, so the work is done once however many
+times it is sent. To make your own retries safe across process restarts, pass
+your own key:
+
+```python
+client.documents.upload(file="bl.pdf", shipment_id=sid, idempotency_key=f"upload-{erp_document_id}")
+```
+
+Uploading the same file to the same shipment twice returns the first document
+(`duplicate=True`) and is not charged again.
+
+## Usage and charges
+
+```python
+usage = client.usage.get()            # this month; or client.usage.get("2026-10")
+for meter in usage.meters:
+    print(meter.name, meter.succeeded, "of", meter.quota or "unlimited")
+print(usage.estimated_charge, usage.currency)
+```
+
+Requests are not charged. Usage is recorded when work completes: a document
+accepted, a document processed, a verification completed. Sandbox usage is
+measured and never charged. Charges are estimates until an invoice is issued.
+
+## Configuration
+
+```python
+ExportFlow(
+    api_key=None,          # default: EXPORTFLOW_API_KEY
+    base_url=None,         # default: EXPORTFLOW_BASE_URL or https://api.exportflow.app
+    timeout=60.0,          # seconds per response
+    max_retries=2,
+    http_client=None,      # your own httpx.Client: proxies, TLS, tests
+)
+```
+
+The client is safe to share between threads. Use it as a context manager, or
+call `close()`, to release its connections.
+
+## Versioning
+
+This SDK follows semantic versioning and speaks version 1 of the API. Within
+version 1 the API only adds; nothing is removed or changed in meaning, so this
+SDK keeps working as the API grows, and unknown fields are available on every
+model's `.raw`. If the server ever reports a different major version the
+client raises `IncompatibleAPIVersionError` rather than misread a response.
+See `CHANGELOG.md`.

exportflow-1.0.0/README.md

@@ -0,0 +1,206 @@
+# ExportFlow Python SDK
+
+The official Python client for the ExportFlow API: upload trade documents from
+your own software, have them classified and read, confirm what they say, and
+verify them against each other.
+
+```bash
+pip install exportflow
+```
+
+Python 3.9 or later. The only dependency is `httpx`.
+
+## Quick start
+
+```python
+from exportflow import ExportFlow
+
+client = ExportFlow(api_key="exfk_test_...")   # or set EXPORTFLOW_API_KEY
+
+# 1. Upload. The document is scanned, stored and queued for processing.
+document = client.documents.upload(file="bill_of_lading.pdf")
+
+# 2. Wait for processing (or use a webhook; see below).
+document = client.documents.wait(document.id)
+print(document.status, document.document_type)        # processed bill_of_lading
+
+# 3. Read what was extracted.
+extraction = client.documents.extraction(document.id)
+print(extraction.as_dict())                           # {"bl_number": "MEDU7741203", ...}
+
+# 4. Confirm what the documents say, then verify the shipment.
+client.records.confirm(document.shipment_id, {"port_of_discharge": "NHAVA SHEVA"})
+verification = client.verifications.create(document.shipment_id)
+verification = client.verifications.wait(verification.id)
+for finding in verification.findings:
+    print(finding.severity, finding.message)
+```
+
+A key that begins `exfk_test_` works in the **sandbox**: the same pipeline,
+separate data, never charged. A key that begins `exfk_live_` is **production**.
+Create both in the developer console.
+
+## How ExportFlow models documents
+
+A **shipment** is a set of documents that travel together: a bill of lading, a
+commercial invoice, a packing list, certificates. Documents are uploaded to a
+shipment, each is **processed** (classified, then its fields extracted), and
+the shipment is **verified** by checking the documents against each other and
+against the published rule set.
+
+`client.documents.upload(file=...)` with no `shipment_id` creates a shipment
+for the document. To group several documents, create the shipment first:
+
+```python
+shipment = client.shipments.create(reference="PO-7741", origin_country="NG",
+                                   destination_country="IN")
+for path in ("bl.pdf", "invoice.pdf", "packing_list.pdf"):
+    client.documents.upload(file=path, shipment_id=shipment.id)
+```
+
+### Why you confirm before you verify
+
+Verification refuses to start (`ConflictError`, code `not_confirmed`) until the
+shipment's record has been confirmed. This is deliberate. If a field was
+misread, every finding computed from it would be wrong, in both directions.
+Show your user what was read (`client.records.get(shipment_id)`), let them
+confirm or correct it, and send that with `client.records.confirm(...)`.
+Confirm what the document *says*, not what it should say: verification is what
+finds the error.
+
+## Webhooks
+
+Polling works; webhooks are better. Register an endpoint once:
+
+```python
+endpoint = client.webhook_endpoints.create(
+    "https://erp.example.com/hooks/exportflow",
+    event_types=["document.processing.completed", "verification.completed"],
+)
+print(endpoint.signing_secret)   # whsec_...  store this
+```
+
+Verify every delivery before trusting it:
+
+```python
+from exportflow import webhooks, SignatureVerificationError
+
+def handle(request):
+    try:
+        event = webhooks.construct_event(
+            payload=request.body,                               # raw bytes
+            signature=request.headers["ExportFlow-Signature"],
+            secret=WEBHOOK_SECRET,
+        )
+    except SignatureVerificationError:
+        return 400
+    if already_handled(event.id):          # deliveries are at-least-once
+        return 200
+    if event.type == "document.processing.completed":
+        document_id = event.data["document"]["id"]
+        ...
+    return 200
+```
+
+Answer with any `2xx` within 10 seconds. Anything else is retried with
+increasing delays for about two and a half hours. An event carries identifiers
+and statuses, never document content: fetch the resource to read it.
+
+| Event | When |
+|---|---|
+| `document.uploaded` | A document was accepted, scanned and stored |
+| `document.processing.started` | Classification began |
+| `document.processing.completed` | The document was classified and read |
+| `document.processing.failed` | Processing stopped; `GET` the document for why |
+| `verification.completed` | A verification finished; fetch it for the findings |
+| `verification.failed` | A verification could not run |
+| `billing.invoice.generated` | An invoice was issued to your organisation |
+
+## Errors
+
+Every error is an `exportflow.ExportFlowError`. One returned by the API is an
+`APIError` with a stable `code`, the HTTP `status_code` and a `request_id` to
+quote to support. Branch on the type or the code, never on the message.
+
+```python
+import exportflow
+
+try:
+    client.verifications.create(shipment_id)
+except exportflow.ConflictError as error:
+    if error.code == "not_confirmed":
+        ...                                   # ask the user to confirm the record
+except exportflow.QuotaExceededError:
+    ...                                       # the month's allowance is used up
+except exportflow.RateLimitError as error:
+    time.sleep(error.retry_after or 5)
+except exportflow.APIConnectionError:
+    ...                                       # safe to retry later
+```
+
+| Exception | HTTP | Meaning |
+|---|---|---|
+| `AuthenticationError` | 401 | Key missing, wrong, revoked or expired |
+| `PermissionDeniedError` | 403 | Missing scope, suspended account, network not allowed |
+| `NotFoundError` | 404 | No such resource in this organisation and environment |
+| `ConflictError` | 409 | Not possible in the current state (e.g. `not_confirmed`) |
+| `InvalidRequestError` | 400, 422 | The request is wrong; do not retry |
+| `RateLimitError` | 429 | Slow down; see `retry_after` |
+| `QuotaExceededError` | 429 | Allowance or spending limit reached for the period |
+| `SDKVersionUnsupportedError` | 426 | Upgrade this SDK |
+| `ServerError` | 5xx | ExportFlow's fault; retried automatically |
+| `APIConnectionError`, `APITimeoutError` | none | The API could not be reached |
+
+## Retries and idempotency
+
+The client retries connection failures, timeouts, `429 rate_limited` and `5xx`
+up to `max_retries` times (default 2), with backoff, honouring `Retry-After`.
+
+Every request that changes something carries an `Idempotency-Key`, and a retry
+sends the *same* key and the *same* body, so the work is done once however many
+times it is sent. To make your own retries safe across process restarts, pass
+your own key:
+
+```python
+client.documents.upload(file="bl.pdf", shipment_id=sid, idempotency_key=f"upload-{erp_document_id}")
+```
+
+Uploading the same file to the same shipment twice returns the first document
+(`duplicate=True`) and is not charged again.
+
+## Usage and charges
+
+```python
+usage = client.usage.get()            # this month; or client.usage.get("2026-10")
+for meter in usage.meters:
+    print(meter.name, meter.succeeded, "of", meter.quota or "unlimited")
+print(usage.estimated_charge, usage.currency)
+```
+
+Requests are not charged. Usage is recorded when work completes: a document
+accepted, a document processed, a verification completed. Sandbox usage is
+measured and never charged. Charges are estimates until an invoice is issued.
+
+## Configuration
+
+```python
+ExportFlow(
+    api_key=None,          # default: EXPORTFLOW_API_KEY
+    base_url=None,         # default: EXPORTFLOW_BASE_URL or https://api.exportflow.app
+    timeout=60.0,          # seconds per response
+    max_retries=2,
+    http_client=None,      # your own httpx.Client: proxies, TLS, tests
+)
+```
+
+The client is safe to share between threads. Use it as a context manager, or
+call `close()`, to release its connections.
+
+## Versioning
+
+This SDK follows semantic versioning and speaks version 1 of the API. Within
+version 1 the API only adds; nothing is removed or changed in meaning, so this
+SDK keeps working as the API grows, and unknown fields are available on every
+model's `.raw`. If the server ever reports a different major version the
+client raises `IncompatibleAPIVersionError` rather than misread a response.
+See `CHANGELOG.md`.

exportflow-1.0.0/pyproject.toml

@@ -0,0 +1,30 @@
+[project]
+name = "exportflow"
+version = "1.0.0"
+description = "The official Python SDK for the ExportFlow document processing and verification API"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "Proprietary" }
+authors = [{ name = "MeerTech Ltd" }]
+keywords = ["exportflow", "documents", "ocr", "trade", "verification", "erp"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Typing :: Typed",
+    "Intended Audience :: Developers",
+]
+dependencies = ["httpx>=0.25,<1"]
+
+[project.urls]
+Documentation = "https://exportflow.app/developers"
+Changelog = "https://exportflow.app/developers/changelog"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/exportflow"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]