Changelog

Added

• Public cryptoai_gateway.telemetry module with two opt-in exporter helpers (TZ-10 §20.7.1):
  • configure_console_exporter() — installs BatchSpanProcessor(ConsoleSpanExporter()) on the global tracer provider. Idempotent.
  • configure_otlp_exporter(endpoint=None, *, headers=None) — installs the OTLP/HTTP exporter. endpoint=None falls back to the TZ-10 §20.7.1 default https://otel.cryptoai-gateway.com/v1/ingest; empty string is rejected. Idempotent. Both helpers raise RuntimeError with a clear install hint when the optional SDK dependency is absent.
• Re-exports at the top level: from cryptoai_gateway import configure_console_exporter, configure_otlp_exporter.
• New optional extra [telemetry-exporters] pulling opentelemetry-sdk>=1.20 + opentelemetry-exporter-otlp-proto-http>=1.20. The previous [telemetry] extra (api-only) is unchanged.

Tests

• 10 new pytest cases in tests/test_telemetry_exporters.py covering reexports, console + OTLP install, idempotency, empty-endpoint rejection, default-endpoint fallback, and the RuntimeError raised when the SDK isn't installed.

Not changed

• Public API surface is otherwise unchanged from 0.1.0 — no breaking changes; the version bump from 0.1.0 to 0.2.0 follows scope decision #15 (pre-1.0 minor bumps on additive feature releases).

First release with real network surface. Not published to PyPI yet — publishing is gated on M5-S2 (t10-release-signing: SLSA L3 + sigstore + PyPI Trusted Publishers / PEP 740).

Added

• CryptoAIClient(api_key=..., base_url=..., timeout_s=...) — async client composing 10 endpoint mixins.
• ClientConfig — frozen dataclass with auth_headers() / base_headers() helpers + redacted __repr__.
• Exception hierarchy (~12 classes): CryptoAIError → CryptoAIClientError / CryptoAIServerError / CryptoAITransportError, with HTTP-status subclasses (Unauthorized, Forbidden, NotFound, Conflict, Gone, UnprocessableEntity, TooManyRequests, ServiceUnavailable, GatewayTimeout) + transport subclasses (ConnectError, ClientTimeoutError, StreamError). Domain logic branches on .code (server's type-URI slug).
• Endpoint mixins: swap, strategies, ai, billing, risk, legal, dsar, onboarding, public, health.
• Idempotency: auto-injects X-Idempotency-Key: <uuid4> on mutating POSTs (/v1/swap/execute, /v1/strategies, /v1/legal/consent, /v1/legal/dsar/request, /v1/aa/session-keys, /v1/onboarding/age-gate). Caller can supply a stable key via idempotency_key=.
• Retry policy: 3 retries (configurable) with full-jitter exponential backoff; honors server-supplied Retry-After on 429 / 503.
• SSE streaming: client.ai.stream_chat(...) returns AsyncIterator[ChatChunk] via httpx.AsyncClient.stream + line-buffered parse.
• Telemetry: opt-in via [telemetry] extra + ClientConfig(telemetry_enabled=True). Per-request OpenTelemetry span with cryptoai.endpoint, cryptoai.request_id, http.method, http.status_code. No-op when opentelemetry-api is not installed.
• Response models: @dataclass(slots, frozen, kw_only) + TypedDict for requests. Forgiving construction (unknown server fields are dropped).
• ASGI transport injection: CryptoAIClient(..., transport=httpx.ASGITransport(app=...)) for in-process integration tests against the FastAPI app.

Tests

• 83 unit cases via httpx.MockTransport covering config, exceptions, internal helpers (idempotency, retry, SSE parser, telemetry), client composition, and the swap / strategies / ai / public / legal / dsar / onboarding mixins.

Distribution

• PyPI distribution name: cryptoai-gateway (formerly skeleton cryptoai-sdk).
• Python import path: cryptoai_gateway (formerly cryptoai_sdk).
• Hatchling build; src/cryptoai_gateway/ layout.
• Runtime deps: httpx>=0.27,<1.0, websockets>=12,<14.
• Optional extras: [validation] (pydantic>=2.6,<3), [telemetry] (opentelemetry-api>=1.20), [dev] (ruff, mypy, pytest, pytest-asyncio, pytest-httpx).

Not yet shipped (deferred to M5-S2+ or later)

• PyPI publishing pipeline (t10-release-signing — M5-S2).
• Auto-generated Pydantic models from docs/openapi.json (M5-S2).
• WebSocket portfolio stream (tz10-ws-catalog — M6+).
• OAuth 2.1 client (tz10-oauth — M6+).
• cag_live_* API-key infrastructure surface (M6+).
• MT5 gateway (tz10-mt5-gateway — M7+).

Added

• Public configureConsoleExporter() + configureOtlpExporter(endpoint, headers?) helpers re-exported from the package root (TZ-10 §20.7.1). Both helpers wrap the OTel SDK install in a single idempotent call and throw with a clear install hint when the optional peer-deps are absent. endpoint = null falls back to the TZ-10 §20.7.1 default (https://otel.cryptoai-gateway.com/v1/ingest); empty string is rejected.
• Optional peer-dep declarations for @opentelemetry/sdk-trace-node and @opentelemetry/exporter-trace-otlp-http (alongside the existing @opentelemetry/api).
• ESM-native lazy peer-dep loading via createRequire(import.meta.url) in src/telemetry.ts so unmodified consumers don't get a bundler-time crash when the peer-deps are absent.

Tests

• 8 new vitest cases in test/telemetry-exporters.test.ts mirroring the Python side (reexports, console + OTLP install, idempotency, empty-endpoint rejection, default-endpoint fallback, header passthrough, _resetForTests state).

Not changed

• Public API surface is otherwise unchanged from 0.1.0 — no breaking changes; the version bump from 0.1.0 to 0.2.0 follows the M5-S2 plan scope decision #15 (pre-1.0 minor bumps on additive feature releases).

First release with real network surface. Not published to npm yet — publishing is gated on M5-S2 (t10-release-signing: sigstore + cosign + npm provenance).

Added

• CryptoAIClient({ apiKey, baseUrl, timeoutMs, ... }) — async client composing 10 endpoint accessors.
• buildConfig({...}) => ClientConfig — frozen config helper with authHeaders(cfg) / baseHeaders(cfg).
• Exception hierarchy (~12 classes): CryptoAIError → CryptoAIClientError / CryptoAIServerError / CryptoAITransportError, with HTTP-status subclasses (Unauthorized, Forbidden, NotFound, Conflict, Gone, UnprocessableEntity, TooManyRequests, ServiceUnavailable, GatewayTimeout) + transport subclasses (ConnectError, ClientTimeoutError, StreamError). Domain logic branches on .code (server's type-URI slug).
• Endpoint accessors: swap, strategies, ai, billing, risk, legal, dsar, onboarding, public, health.
• Idempotency: auto-injects X-Idempotency-Key (via crypto.randomUUID()) on mutating POSTs. Caller override via idempotencyKey:.
• Retry policy: 3 retries (configurable) with full-jitter exponential backoff; honors server-supplied Retry-After on 429 / 503.
• SSE streaming: client.ai.streamChat({...}) returns AsyncGenerator<ChatChunk> via fetch + ReadableStream + line-buffered parse.
• Telemetry: opt-in via @opentelemetry/api peer dep + telemetryEnabled: true. Per-request OpenTelemetry span. No-op when the peer dep is not installed.
• Custom fetch injection: new CryptoAIClient({ fetch: customFetch }) for tests + middleware (logging, instrumentation, retries).
• TypeScript: full type definitions for 20+ response + request shapes (Strategy, Swap, ChatRequest, etc.). ESM-only; targets ES2022.

Tests

• 64 vitest cases covering client (auth, idempotency, retry, error mapping), exceptions (status map, code extraction, Retry-After parsing), internal helpers (backoff, isRetryable, runWithRetry, SSE parser), and the swap / strategies / ai / public / legal / dsar / onboarding accessors.

Distribution

• npm distribution name: @cryptoai/gateway (formerly skeleton @cryptoai/sdk).
• ESM-only. Build = tsc -p tsconfig.json (no bundler, matches the @cryptoai/aa precedent). Output: dist/ with .js + .d.ts + source maps.
• Node ≥20. Native fetch + WebSocket + crypto.randomUUID().
• Optional peer dep: @opentelemetry/api ^1.7.0.

Not yet shipped (deferred to M5-S2+ or later)

• npm publishing pipeline (t10-release-signing — M5-S2).
• Auto-generated TS types from docs/openapi.json (M5-S2).
• WebSocket portfolio stream (tz10-ws-catalog — M6+).
• OAuth 2.1 client (tz10-oauth — M6+).
• cag_live_* API-key infrastructure surface (M6+).
• MT5 gateway (tz10-mt5-gateway — M7+).