fxmacrodata-platform-core 0.1.0__py3-none-any.whl

fxmacrodata_platform_core/__init__.py

@@ -0,0 +1,4 @@
+"""Customer-side adapters for documented FXMacroData public contracts."""
+from .core import Batch, COLUMNS, IntegrationError, operations, read, schemas, validate_request
+
+__all__ = ["Batch", "COLUMNS", "IntegrationError", "operations", "read", "schemas", "validate_request"]

fxmacrodata_platform_core/core.py

@@ -0,0 +1,268 @@
+"""Lossless result envelopes and bounded customer-side reads."""
+from __future__ import annotations
+
+from copy import deepcopy
+from dataclasses import dataclass
+import hashlib
+from importlib.resources import files
+import json
+import math
+import os
+import re
+from typing import Any
+
+import jsonschema
+from fxmacrodata_public import FXMacroDataClient, Operation, Result
+from fxmacrodata_public.client import SCHEMA_REGISTRY
+from fxmacrodata_public.transport import redact_text
+from fxmacrodata_public.pagination import iter_pages
+
+COLUMNS = ("operation", "source_url", "record_id", "currency", "indicator", "date",
+           "announcement_datetime", "value", "value_text", "record_json", "response_json")
+_FORBIDDEN = {"apikey", "accesstoken", "authorization", "password", "clientsecret",
+              "secret", "token", "url", "baseurl", "endpoint"}
+
+
+class IntegrationError(RuntimeError):
+    """A credential-free configuration or read failure."""
+
+
+def operations() -> tuple[Operation, ...]:
+    base = files(__package__)
+    rest = json.loads(base.joinpath("operations.json").read_text(encoding="utf-8"))
+    mcp = json.loads(base.joinpath("mcp-tools.json").read_text(encoding="utf-8"))
+    result = [Operation(**{**item, "parameters": tuple(item.get("parameters", []))}) for item in rest]
+    result.extend(Operation("mcp_" + t["name"], t.get("description", t["name"]),
+                            t["inputSchema"], "/mcp", "MCP") for t in mcp)
+    return tuple(result)
+
+
+def schemas() -> dict[str, dict]:
+    return {op.name: deepcopy(op.input_schema) for op in operations()}
+
+
+def _json(value: Any) -> str:
+    return json.dumps(value, sort_keys=True, ensure_ascii=False, separators=(",", ":"), allow_nan=False)
+
+
+def _text(value: Any) -> str | None:
+    return None if value is None else str(value)
+
+
+@dataclass(frozen=True)
+class Batch:
+    """Original public response and additive tabular projections."""
+    operation: str
+    payload: Any
+    source_url: str = "https://fxmacrodata.com"
+
+    def records(self) -> list[dict]:
+        if isinstance(self.payload, dict) and isinstance(self.payload.get("versions"), list):
+            return deepcopy(self.payload["versions"])
+        if self.operation == "mcp_calendar_event_versions":
+            page = _cursor_page(self.payload)
+            if isinstance(page.get("versions"), list):
+                return deepcopy(page["versions"])
+        return Result(self.operation, self.payload, self.source_url).records()
+
+    def rows(self) -> list[dict]:
+        response = _json(self.payload)
+        output = []
+        for record in self.records() or [None]:
+            values = record if isinstance(record, dict) else {}
+            value = values.get("value", values.get("val"))
+            numeric = None
+            if value is not None and not isinstance(value, bool):
+                try:
+                    parsed = float(value)
+                    if math.isfinite(parsed):
+                        numeric = parsed
+                except (TypeError, ValueError, OverflowError):
+                    pass
+            encoded = _json(record)
+            identity = _json([self.operation, record if record is not None else self.payload])
+            output.append(dict(zip(COLUMNS, (
+                self.operation, self.source_url, hashlib.sha256(identity.encode()).hexdigest(),
+                _text(values.get("currency")), _text(values.get("indicator")),
+                _text(values.get("date")), _text(values.get("announcement_datetime")),
+                numeric, _text(value), encoded, response,
+            ))))
+        return output
+
+
+def _validate(value: Any) -> None:
+    if isinstance(value, dict):
+        for key, item in value.items():
+            if not isinstance(key, str) or re.sub(r"[_-]", "", key.lower()) in _FORBIDDEN:
+                raise IntegrationError("Use a runtime secret reference; credentials and endpoint overrides are not arguments.")
+            _validate(item)
+    elif isinstance(value, list):
+        for item in value:
+            _validate(item)
+
+
+def _redact(value: Any, secret: str) -> Any:
+    if isinstance(value, str):
+        return redact_text(value, secret)
+    if isinstance(value, list):
+        return [_redact(item, secret) for item in value]
+    if isinstance(value, dict):
+        return {_redact(str(k), secret): "[redacted]" if re.sub(r"[_-]", "", str(k).lower()) in _FORBIDDEN - {"url", "baseurl", "endpoint"}
+                else _redact(v, secret) for k, v in value.items()}
+    return value
+
+
+def validate_request(operation: str, arguments: dict | None = None) -> dict:
+    """Validate before a lazy source or pipeline can serialize arguments."""
+    inventory = {item.name: item for item in operations()}
+    if not isinstance(operation, str) or operation not in inventory:
+        raise IntegrationError("Unknown operation; inspect schemas() for supported operations.")
+    if arguments is not None and not isinstance(arguments, dict):
+        raise IntegrationError("Operation arguments must be an object.")
+    args = deepcopy(arguments or {})
+    _validate(args)
+    try:
+        jsonschema.Draft202012Validator(inventory[operation].input_schema, registry=SCHEMA_REGISTRY).validate(args)
+    except Exception:
+        raise IntegrationError("Invalid arguments; inspect the operation's input schema.") from None
+    return args
+
+
+class _HeaderClient(FXMacroDataClient):
+    """Use public API-key headers rather than credentials in request URLs."""
+    def _auth_params(self):
+        return {}
+
+    def _request(self, method, url, *, headers=None, **kwargs):
+        headers = dict(headers or {})
+        if self._api_key:
+            headers["X-API-Key"] = self._api_key
+        return super()._request(method, url, headers=headers, **kwargs)
+
+
+def _cursor_page(payload):
+    if isinstance(payload, dict) and "checkpoint" in payload:
+        return payload
+    if isinstance(payload, dict):
+        for name in ("structuredContent", "result"):
+            if isinstance(payload.get(name), dict):
+                return _cursor_page(payload[name])
+        for block in payload.get("content", []):
+            if isinstance(block, dict) and block.get("type") == "text":
+                try:
+                    candidate = json.loads(block["text"])
+                except (KeyError, TypeError, ValueError):
+                    continue
+                if isinstance(candidate, dict) and "checkpoint" in candidate:
+                    return candidate
+    raise IntegrationError("Calendar response omitted its archive checkpoint.")
+
+
+def _cursor_history(client, operation, args, max_pages):
+    if args.get("cursor"):
+        raise IntegrationError("Complete calendar history starts without a cursor.")
+    field = "versions" if "event_versions" in operation else "events"
+    query, pages, rows, seen = dict(args), [], [], set()
+    checkpoint = args.get("checkpoint")
+    source = "https://fxmacrodata.com"
+    for _ in range(max_pages):
+        result = client.execute(operation, query)
+        page = _cursor_page(result.payload)
+        current = page.get("checkpoint")
+        if type(current) is not int or (checkpoint is not None and current != checkpoint):
+            raise IntegrationError("Calendar archive checkpoint changed; restart the read.")
+        checkpoint = current
+        data = page.get(field)
+        if not isinstance(data, list):
+            raise IntegrationError("Calendar response omitted its record array.")
+        pages.append(deepcopy(result.payload))
+        rows.extend(deepcopy(data))
+        source = result.source_url
+        cursor = page.get("next_cursor")
+        if cursor is None:
+            return Result(operation, {field: rows, "complete": True, "checkpoint": checkpoint,
+                                      "next_cursor": None, "pages": pages}, source)
+        if not isinstance(cursor, str) or not cursor or cursor in seen or not data:
+            raise IntegrationError("Calendar cursor did not advance; history is incomplete.")
+        seen.add(cursor)
+        query.update(cursor=cursor, checkpoint=checkpoint)
+    raise IntegrationError("Calendar history exceeded the explicit page budget.")
+
+
+def _offset_history(client, operation, args, max_pages):
+    pages, rows, source = [], [], "https://fxmacrodata.com"
+    query = dict(args)
+    query.pop("page", None)
+    def fetch(arguments):
+        nonlocal source
+        result = client.execute(operation, arguments)
+        source = result.source_url
+        pages.append(deepcopy(result.payload))
+        return result.payload
+    checkpoint = None
+    for page in iter_pages(fetch, query, max_pages=max_pages, request_id=operation, require_pagination=True):
+        rows.extend(deepcopy(page["data"]))
+        checkpoint = page["client_resume"]
+    return Result(operation, {"data":rows, "complete":True, "pages":pages,
+                              "client_resume":checkpoint}, source)
+
+
+def read(operation: str, arguments: dict | None = None, *, api_key_env: str | None = None,
+         complete_history: bool = True, max_pages: int = 10000, client_factory=None) -> Batch:
+    """Read a documented operation without serializing or logging a credential.
+
+    Omitting api_key_env explicitly selects anonymous access, even when an
+    unrelated API key exists in the environment. Every result retains its
+    original envelope; empty results still have one metadata envelope row.
+    """
+    inventory = {item.name: item for item in operations()}
+    if not isinstance(operation, str) or operation not in inventory:
+        raise IntegrationError("Unknown operation; inspect schemas() for supported operations.")
+    if arguments is not None and not isinstance(arguments, dict):
+        raise IntegrationError("Operation arguments must be an object.")
+    args = validate_request(operation, arguments)
+    if type(max_pages) is not int or not 1 <= max_pages <= 10000 or type(complete_history) is not bool:
+        raise IntegrationError("Use a boolean history option and page budget between 1 and 10000.")
+    secret = ""
+    if api_key_env is not None:
+        if not isinstance(api_key_env, str) or not re.fullmatch(r"[A-Z][A-Z0-9_]{0,127}", api_key_env):
+            raise IntegrationError("Use an environment-variable name for the API key.")
+        secret = os.environ.get(api_key_env, "")
+        if not secret:
+            raise IntegrationError("The named API-key environment variable is unavailable.")
+    selected = inventory[operation]
+    try:
+        jsonschema.Draft202012Validator(selected.input_schema, registry=SCHEMA_REGISTRY).validate(args)
+    except Exception:
+        raise IntegrationError("Invalid arguments; inspect the operation's input schema.") from None
+    paginated = selected.method == "GET" and any(p["name"] == "offset" for p in selected.parameters)
+    if complete_history and paginated and (args.get("offset", 0) != 0 or args.get("page", 1) != 1):
+        raise IntegrationError("Complete history starts at offset zero; use complete_history=False for an individual page.")
+    factory = client_factory or _HeaderClient
+    client = None
+    try:
+        client = factory(api_key=secret)
+        # The dependency is a public client with a smaller packaged catalogue.
+        # Supplement its public descriptors without importing service code.
+        if isinstance(client, FXMacroDataClient):
+            client._operations = inventory
+        if complete_history and operation in {"calendar_snapshot", "calendar_event_versions", "mcp_calendar_snapshot", "mcp_calendar_event_versions"}:
+            result = _cursor_history(client, operation, args, max_pages)
+        elif complete_history and paginated:
+            result = _offset_history(client, operation, args, max_pages)
+        else:
+            result = client.execute(operation, args)
+        payload = _redact(deepcopy(result.payload), secret)
+        # Fail closed on invalid JSON rather than storing platform-specific guesses.
+        _json(payload)
+        return Batch(operation, payload, _redact(result.source_url, secret))
+    except IntegrationError:
+        raise
+    except Exception:
+        raise IntegrationError("FXMacroData read failed; check credentials, operation arguments and service availability.") from None
+    finally:
+        if client is not None:
+            try:
+                client.close()
+            except Exception:
+                pass