distyra 0.1.0__tar.gz

distyra-0.1.0/.gitignore

@@ -0,0 +1,90 @@
+node_modules/
+dist/
+.wrangler/
+.dev.vars
+*.log
+.DS_Store
+.env
+.env.local
+
+# Python (packages/saas-sdk-python)
+__pycache__/
+*.egg-info/
+.venv/
+
+# Deployment-specific files (never commit real credentials)
+.env.secrets
+.env.production
+.scaleway-config
+scripts/netcup-frozen/.netcup-config
+scripts/netcup-frozen/backup.env
+
+# OVH deploy: .ovh-config is COMMITTED but ansible-vault encrypted; only the
+# vault password file is gitignored. See scripts/ovh/VAULT.md.
+scripts/ovh/.vault_pass
+
+# DR Phase 1: provisioning orchestrator (provision-de1.sh) writes captured
+# public IPs here for downstream scripts. Contains no secrets (IPs are public)
+# but is per-environment state, not source. The operator copies values from
+# this file into the ansible-vault via `ansible-vault edit`.
+scripts/ovh/.de1-provisioned.json
+
+# DR Phase 2: etcd cluster TLS certificate material. Generated locally by
+# scripts/ovh/etcd/gen-certs.sh, distributed via SSH to the 3 cluster nodes.
+# Contains the etcd CA private key — operator MUST back this up to offline
+# paper-anchor storage alongside the vault password.
+scripts/ovh/etcd/certs/
+
+# DR Phase 2c-prep: Patroni cluster-internal secrets (replication password,
+# rewind password, REST API HTTP basic auth). Generated locally by
+# scripts/ovh/patroni/setup-patroni-de1-replica.sh, distributed via SSH to
+# Patroni nodes. Used by Patroni for inter-node auth + the management API.
+# Back up to offline storage alongside etcd/certs/ca-key.pem.
+scripts/ovh/patroni/secrets/
+redis-data/
+.scaleway/
+*.scw
+*.pem
+
+# Cloudflare backup exports (contain merchant data)
+cf-backup/
+
+# Real bank-statement fixtures for parser/ingest testing (never commit)
+statements/
+
+# Build outputs
+*.tgz
+
+# Eval-harness CSV outputs
+out/
+
+# Next.js dev/build artifacts (apps/admin)
+.next/
+
+# Deprecated Cloudflare code
+deprecated/
+
+# Claude Code session-local artifacts
+.claude/
+
+# Smoke-test working dir (scripts/test-sek-canary.ts writes synthetic
+# fixtures here; never commit real or synthetic bank-statement payloads)
+tmp/
+
+# HTTP archives (DevTools/Charles exports). They capture full
+# request/response incl. auth headers, cookies, OAuth code/state and
+# App Attest assertions, so they MUST never be committed (privacy policy).
+# Two were found tracked in docs/ on 2026-06-01; see HISTORY_PURGE_NEEDED.md.
+*.har
+
+# TypeScript incremental build cache. Was tracked by mistake; it is a build
+# artifact that re-dirties the tree on every compile. Untracked 2026-06-02.
+*.tsbuildinfo
+
+# Local-only docs, kept OUT of git by deliberate choice (2026-06-02):
+#  - docs/Distyra-Logo/: brand design working material (mockups, scratch, a ZIP,
+#    a generated image) — not code-repo content; lives on the operator's machine.
+#  - the Enable Banking agreement: a confidential signed contract that must not
+#    sit in clonable git history; keep it in the document store instead.
+docs/Distyra-Logo/
+docs/Enable_Banking_Agreement.pdf

distyra-0.1.0/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: distyra
+Version: 0.1.0
+Summary: Python client for the Distyra Transaction Enrichment API (enrichment + SME underwriting)
+Project-URL: Homepage, https://distyra.com
+Project-URL: Documentation, https://api.distyra.com/docs
+Author: Brightfield Software
+License: MIT
+Keywords: distyra,open banking,psd2,transaction enrichment,underwriting
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: attrs>=22.2.0
+Requires-Dist: httpx<0.29.0,>=0.23.0
+Requires-Dist: python-dateutil<3,>=2.8.0
+Description-Content-Type: text/markdown
+
+# distyra
+
+Python client for the [Distyra Transaction Enrichment API](https://api.distyra.com/docs): transaction enrichment and SME cash-flow underwriting for EU lenders.
+
+```bash
+pip install distyra
+```
+
+## Quick start
+
+```python
+import os
+from distyra import Distyra
+
+client = Distyra(api_key=os.environ["DISTYRA_API_KEY"])
+
+result = client.enrich(
+    descriptor="ALBERT HEIJN 1234 AMSTERDAM NL",
+    amount=-12.34,
+    currency="EUR",
+    mcc="5411",
+)
+print(result.merchant.name)        # "Albert Heijn"
+print(result.category.primary)     # "Retail & E-commerce"
+print(result.category.source)      # "catalog" (curated) or "llm" (model-proposed)
+```
+
+## Batch enrichment
+
+```python
+batch = client.enrich_batch([
+    {"descriptor": "ALBERT HEIJN 1234 AMSTERDAM NL", "amount": -12.34, "currency": "EUR"},
+    {"descriptor": "NS GROEP B.V.", "amount": -4.50, "currency": "EUR"},
+    {"descriptor": "NETFLIX.COM", "amount": -13.99, "currency": "EUR"},
+])
+for item in batch.items:
+    print(item)
+```
+
+Up to 100 items per call; a failed item occupies its slot with an error envelope, the batch itself never fails.
+
+## Underwriting
+
+Statement files in, one consolidated analysis out. Multiple files for the same applicant (the "last 6 months as 6 monthly PDFs" case) consolidate into one analysis over the merged window:
+
+```python
+analysis = client.analyze_statement(
+    ["jan.pdf", "feb.pdf", "mar.pdf"],
+    applicant_id="loan-2026-0142",
+    input_mode="statement_pdf",     # one format per analysis
+    enrich=True,                    # optional: enrich every transaction
+)
+print(analysis.id, analysis.features)
+```
+
+JSON mode, when transactions are already on hand:
+
+```python
+analysis = client.analyze(
+    applicant_id="loan-2026-0142",
+    input_mode="raw",
+    accounts=[{
+        "account_id": "main",
+        "currency": "EUR",
+        "opening_balance": 1500.0,
+        "transactions": [
+            {"date": "2026-05-01", "amount": 2500.0, "descriptor_raw": "INVOICE 1001 ACME BV"},
+            {"date": "2026-05-15", "amount": -1200.0, "descriptor_raw": "RENT MAY OFFICE"},
+        ],
+    }],
+)
+```
+
+Fetch a stored analysis later with `client.get_analysis(analysis_id)`.
+
+Note: enrichment is self-serve; underwriting endpoints are enabled per organization. Contact sales for access.
+
+## Errors
+
+Every non-2xx raises `DistyraError` with the parsed envelope:
+
+```python
+from distyra import Distyra, DistyraError
+
+try:
+    client.enrich(descriptor="...")
+except DistyraError as e:
+    print(e.status_code, e.error, e.detail)
+```
+
+## Beyond the wrapper
+
+The full generated client (every endpoint, typed models) ships in the same distribution as `distyra_api_client`. The wrapper's `.raw` attribute is a ready-authenticated instance:
+
+```python
+from distyra_api_client.api.catalog import get_categories
+
+categories = get_categories.sync(client=client.raw)
+```
+
+## Development
+
+This package lives in the Distyra monorepo at `packages/saas-sdk-python/`. The `distyra_api_client` package is generated from the committed OpenAPI snapshot — do not edit it by hand:
+
+```bash
+npm run snapshot -w @brightfield/saas-api   # refresh openapi.json from source
+bash scripts/generate-python-sdk.sh         # regenerate distyra_api_client
+bash scripts/test-python-sdk.sh             # build wheel + smoke
+```

distyra-0.1.0/README.md

@@ -0,0 +1,109 @@
+# distyra
+
+Python client for the [Distyra Transaction Enrichment API](https://api.distyra.com/docs): transaction enrichment and SME cash-flow underwriting for EU lenders.
+
+```bash
+pip install distyra
+```
+
+## Quick start
+
+```python
+import os
+from distyra import Distyra
+
+client = Distyra(api_key=os.environ["DISTYRA_API_KEY"])
+
+result = client.enrich(
+    descriptor="ALBERT HEIJN 1234 AMSTERDAM NL",
+    amount=-12.34,
+    currency="EUR",
+    mcc="5411",
+)
+print(result.merchant.name)        # "Albert Heijn"
+print(result.category.primary)     # "Retail & E-commerce"
+print(result.category.source)      # "catalog" (curated) or "llm" (model-proposed)
+```
+
+## Batch enrichment
+
+```python
+batch = client.enrich_batch([
+    {"descriptor": "ALBERT HEIJN 1234 AMSTERDAM NL", "amount": -12.34, "currency": "EUR"},
+    {"descriptor": "NS GROEP B.V.", "amount": -4.50, "currency": "EUR"},
+    {"descriptor": "NETFLIX.COM", "amount": -13.99, "currency": "EUR"},
+])
+for item in batch.items:
+    print(item)
+```
+
+Up to 100 items per call; a failed item occupies its slot with an error envelope, the batch itself never fails.
+
+## Underwriting
+
+Statement files in, one consolidated analysis out. Multiple files for the same applicant (the "last 6 months as 6 monthly PDFs" case) consolidate into one analysis over the merged window:
+
+```python
+analysis = client.analyze_statement(
+    ["jan.pdf", "feb.pdf", "mar.pdf"],
+    applicant_id="loan-2026-0142",
+    input_mode="statement_pdf",     # one format per analysis
+    enrich=True,                    # optional: enrich every transaction
+)
+print(analysis.id, analysis.features)
+```
+
+JSON mode, when transactions are already on hand:
+
+```python
+analysis = client.analyze(
+    applicant_id="loan-2026-0142",
+    input_mode="raw",
+    accounts=[{
+        "account_id": "main",
+        "currency": "EUR",
+        "opening_balance": 1500.0,
+        "transactions": [
+            {"date": "2026-05-01", "amount": 2500.0, "descriptor_raw": "INVOICE 1001 ACME BV"},
+            {"date": "2026-05-15", "amount": -1200.0, "descriptor_raw": "RENT MAY OFFICE"},
+        ],
+    }],
+)
+```
+
+Fetch a stored analysis later with `client.get_analysis(analysis_id)`.
+
+Note: enrichment is self-serve; underwriting endpoints are enabled per organization. Contact sales for access.
+
+## Errors
+
+Every non-2xx raises `DistyraError` with the parsed envelope:
+
+```python
+from distyra import Distyra, DistyraError
+
+try:
+    client.enrich(descriptor="...")
+except DistyraError as e:
+    print(e.status_code, e.error, e.detail)
+```
+
+## Beyond the wrapper
+
+The full generated client (every endpoint, typed models) ships in the same distribution as `distyra_api_client`. The wrapper's `.raw` attribute is a ready-authenticated instance:
+
+```python
+from distyra_api_client.api.catalog import get_categories
+
+categories = get_categories.sync(client=client.raw)
+```
+
+## Development
+
+This package lives in the Distyra monorepo at `packages/saas-sdk-python/`. The `distyra_api_client` package is generated from the committed OpenAPI snapshot — do not edit it by hand:
+
+```bash
+npm run snapshot -w @brightfield/saas-api   # refresh openapi.json from source
+bash scripts/generate-python-sdk.sh         # regenerate distyra_api_client
+bash scripts/test-python-sdk.sh             # build wheel + smoke
+```

distyra-0.1.0/distyra/__init__.py

@@ -0,0 +1,34 @@
+"""distyra — Python client for the Distyra Transaction Enrichment API.
+
+Two layers, mirroring the TypeScript SDK (@brightfield/saas-sdk):
+
+  - ``distyra_api_client`` — fully generated from the OpenAPI snapshot in
+    apps/saas-api/openapi.json (openapi-python-client). Typed models +
+    per-endpoint modules. Use it directly for anything the wrapper below
+    doesn't cover::
+
+        from distyra_api_client.api.catalog import get_categories
+        cats = get_categories.sync(client=sdk.raw)
+
+  - ``Distyra`` — opinionated wrapper for the headline calls: enrich,
+    enrich_batch, analyze (JSON mode), analyze_statement (multipart file
+    upload — hand-rolled because Fastify's multipart endpoints carry no
+    body schema in the spec), get_analysis.
+
+Regenerate after any saas-api schema change (from the repo root):
+
+    1. npm run snapshot -w @brightfield/saas-api    # refresh openapi.json
+    2. bash scripts/generate-python-sdk.sh          # regen distyra_api_client
+
+The committed snapshot makes regen reproducible from git without a running
+server — same contract as the TS SDK.
+"""
+
+from .client import (
+    Distyra,
+    DistyraError,
+    PRODUCTION_BASE_URL,
+)
+
+__all__ = ["Distyra", "DistyraError", "PRODUCTION_BASE_URL"]
+__version__ = "0.1.0"

distyra-0.1.0/distyra/client.py

@@ -0,0 +1,219 @@
+"""Opinionated wrapper around the generated ``distyra_api_client``.
+
+Raises ``DistyraError`` on every non-2xx so happy-path code never touches
+status unions; drops to the generated layer (``.raw``) for everything else.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Iterable, Optional, Sequence, Union
+
+from distyra_api_client import AuthenticatedClient
+from distyra_api_client.api.enrichment import enrich_batch, enrich_single
+from distyra_api_client.api.underwriting import (
+    analyze_applicant,
+    get_underwriting_analysis,
+)
+from distyra_api_client.models import (
+    AnalyzeApplicantBody,
+    AnalyzeApplicantFromStatementResponse200,
+    AnalyzeApplicantResponse200,
+    EnrichBatchBody,
+    EnrichBatchResponse200,
+    EnrichSingleBody,
+    EnrichSingleResponse200,
+    GetUnderwritingAnalysisResponse200,
+)
+from distyra_api_client.types import Response
+
+#: Production base URL — Bunny Shield → Caddy origin → saas-api. Mirrors the
+#: OpenAPI ``servers[0]`` entry; kept in sync by hand (same contract as the
+#: TS SDK's PRODUCTION_BASE_URL).
+PRODUCTION_BASE_URL = "https://api.distyra.com"
+
+#: One statement file: a path, raw bytes, or a (filename, bytes) /
+#: (filename, bytes, content_type) tuple.
+StatementFile = Union[str, Path, bytes, tuple]
+
+_CONTENT_TYPES = {
+    ".xml": "application/xml",
+    ".sta": "text/plain",
+    ".mt940": "text/plain",
+    ".940": "text/plain",
+    ".txt": "text/plain",
+    ".pdf": "application/pdf",
+    ".csv": "text/csv",
+}
+
+
+class DistyraError(Exception):
+    """Non-2xx API response. Carries the parsed error envelope when present."""
+
+    def __init__(self, status_code: int, error: str, detail: Optional[str] = None):
+        self.status_code = status_code
+        self.error = error
+        self.detail = detail
+        super().__init__(
+            f"HTTP {status_code}: {error}" + (f" — {detail}" if detail else "")
+        )
+
+    @classmethod
+    def from_response(cls, status_code: int, content: bytes) -> "DistyraError":
+        try:
+            body = json.loads(content)
+            return cls(status_code, body.get("error", "unknown_error"), body.get("detail"))
+        except (json.JSONDecodeError, AttributeError):
+            return cls(status_code, content.decode(errors="replace")[:200] or "unknown_error")
+
+
+def _unwrap(resp: Response, ok_type: type) -> Any:
+    """Return the parsed 2xx model or raise DistyraError."""
+    if 200 <= resp.status_code < 300 and isinstance(resp.parsed, ok_type):
+        return resp.parsed
+    raise DistyraError.from_response(resp.status_code, resp.content)
+
+
+class Distyra:
+    """Client for the Distyra Transaction Enrichment API.
+
+    Example::
+
+        from distyra import Distyra
+
+        client = Distyra(api_key=os.environ["DISTYRA_API_KEY"])
+        result = client.enrich(
+            descriptor="ALBERT HEIJN 1234 AMSTERDAM NL",
+            amount=-12.34,
+            currency="EUR",
+        )
+        print(result.merchant.name, result.category.primary, result.category.source)
+
+    ``base_url`` defaults to production; override for local/staging. The
+    underlying generated client (httpx) is exposed as ``.raw`` for endpoints
+    the wrapper doesn't cover.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = PRODUCTION_BASE_URL,
+        timeout: float = 30.0,
+        **httpx_kwargs: Any,
+    ):
+        if not api_key:
+            raise ValueError("Distyra: api_key is required")
+        import httpx  # local import keeps module import cheap
+
+        self.raw = AuthenticatedClient(
+            base_url=base_url,
+            token=api_key,
+            timeout=httpx.Timeout(timeout),
+            raise_on_unexpected_status=False,
+            **httpx_kwargs,
+        )
+
+    # ─── Enrichment ────────────────────────────────────────────────────────
+
+    def enrich(self, descriptor: str, **fields: Any) -> EnrichSingleResponse200:
+        """POST /v1/enrich — synchronous single-transaction cascade.
+
+        ``fields``: amount, currency, mcc, country_hint, merchant_name,
+        bank_code_description (all optional, see the API reference).
+        """
+        body = EnrichSingleBody.from_dict({"descriptor": descriptor, **fields})
+        resp = enrich_single.sync_detailed(client=self.raw, body=body)
+        return _unwrap(resp, EnrichSingleResponse200)
+
+    def enrich_batch(self, items: Iterable[dict]) -> EnrichBatchResponse200:
+        """POST /v1/enrich/batch — up to 100 items, per-item failure slots."""
+        body = EnrichBatchBody.from_dict({"items": list(items)})
+        resp = enrich_batch.sync_detailed(client=self.raw, body=body)
+        return _unwrap(resp, EnrichBatchResponse200)
+
+    # ─── Underwriting ──────────────────────────────────────────────────────
+
+    def analyze(self, **payload: Any) -> AnalyzeApplicantResponse200:
+        """POST /v1/underwrite/analyze — JSON mode (raw or enriched txns).
+
+        ``payload`` is the request body: applicant_id, input_mode, accounts,
+        analysis_window?, options? — see the API reference.
+        """
+        body = AnalyzeApplicantBody.from_dict(payload)
+        resp = analyze_applicant.sync_detailed(client=self.raw, body=body)
+        return _unwrap(resp, AnalyzeApplicantResponse200)
+
+    def analyze_statement(
+        self,
+        files: Union[StatementFile, Sequence[StatementFile]],
+        *,
+        applicant_id: str,
+        input_mode: str,
+        enrich: bool = False,
+        allow_partial: bool = False,
+        analysis_window: Optional[dict] = None,
+    ) -> AnalyzeApplicantFromStatementResponse200:
+        """POST /v1/underwrite/analyze/statement — multipart statement upload.
+
+        One applicant, one or more statement files (the "6 monthly PDFs"
+        case) → ONE consolidated analysis. ``input_mode`` is the statement
+        format discriminator (e.g. ``statement_camt053``, ``statement_mt940``,
+        ``statement_pdf`` — one format per analysis).
+
+        Hand-rolled multipart: Fastify's multipart endpoints carry no body
+        schema in the OpenAPI spec, so the generated layer can't drive this
+        endpoint. The 200 response IS in the spec and parses into the
+        generated model.
+        """
+        meta: dict = {"applicant_id": applicant_id, "input_mode": input_mode}
+        if allow_partial:
+            meta["allow_partial"] = True
+        if analysis_window is not None:
+            meta["analysis_window"] = analysis_window
+
+        file_list = (
+            [files]
+            if isinstance(files, (str, Path, bytes, tuple))
+            else list(files)
+        )
+        parts = [("file", _to_file_part(f, i)) for i, f in enumerate(file_list)]
+
+        httpx_client = self.raw.get_httpx_client()
+        resp = httpx_client.post(
+            "/v1/underwrite/analyze/statement",
+            params={"enrich": "true"} if enrich else None,
+            data={"meta": json.dumps(meta)},
+            files=parts,
+        )
+        if not (200 <= resp.status_code < 300):
+            raise DistyraError.from_response(resp.status_code, resp.content)
+        return AnalyzeApplicantFromStatementResponse200.from_dict(resp.json())
+
+    def get_analysis(self, analysis_id: str) -> GetUnderwritingAnalysisResponse200:
+        """GET /v1/underwrite/analyses/{id}."""
+        resp = get_underwriting_analysis.sync_detailed(client=self.raw, id=analysis_id)
+        return _unwrap(resp, GetUnderwritingAnalysisResponse200)
+
+    # ─── Lifecycle ─────────────────────────────────────────────────────────
+
+    def close(self) -> None:
+        self.raw.get_httpx_client().close()
+
+    def __enter__(self) -> "Distyra":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+
+def _to_file_part(f: StatementFile, index: int) -> tuple:
+    """Normalize a StatementFile into an httpx files= tuple."""
+    if isinstance(f, tuple):
+        return f if len(f) >= 2 else (f"statement-{index}", f[0])
+    if isinstance(f, bytes):
+        return (f"statement-{index}", f)
+    path = Path(f)
+    content_type = _CONTENT_TYPES.get(path.suffix.lower(), "application/octet-stream")
+    return (path.name, path.read_bytes(), content_type)

distyra-0.1.0/distyra_api_client/__init__.py

@@ -0,0 +1,8 @@
+"""A client library for accessing Distyra Transaction Enrichment API"""
+
+from .client import AuthenticatedClient, Client
+
+__all__ = (
+    "AuthenticatedClient",
+    "Client",
+)

distyra-0.1.0/distyra_api_client/api/__init__.py

@@ -0,0 +1 @@
+"""Contains methods for accessing the API"""

distyra-0.1.0/distyra_api_client/api/authentication/__init__.py

@@ -0,0 +1 @@
+"""Contains endpoint functions for accessing the API"""