Metadata-Version: 2.4
Name: nats-fxmacrodata
Version: 0.1.0
Summary: Publish public FXMacroData responses to NATS JetStream
License-Expression: MIT
Project-URL: Documentation, https://fxmacrodata.com/documentation/reference?utm_source=pypi&utm_medium=referral&utm_campaign=nats-fxmacrodata&utm_content=package
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fxmacrodata-platform-core==0.1.0
Requires-Dist: nats-py<3,>=2.16.0
Provides-Extra: test
Requires-Dist: pytest<9,>=8; extra == "test"
Dynamic: license-file

# FXMacroData for NATS JetStream

Publish FXMacroData public responses to a JetStream subject with the official
`nats-py` client. Stream macro announcements to your own consumers while
retaining the source payload and revision metadata.

[FXMacroData documentation](https://fxmacrodata.com/documentation/reference?utm_source=github&utm_medium=referral&utm_campaign=nats-fxmacrodata&utm_content=readme)

## Install and connect

Requires Python 3.10 or later. Install this package and its adjacent public
client dependencies from the distribution supplied to you:

```sh
python -m pip install /path/to/fxmacrodata-public-client /path/to/fxmacrodata-platform-core /path/to/nats-fxmacrodata
```

Configure `NATS_URL` and any credentials file in your runtime secret store.
Then publish to a subject captured by a customer-owned stream:

```python
import asyncio
import os
import nats
from fxmacrodata_platform_core import read
from fxmacrodata_nats import publish


async def main():
    client = await nats.connect(os.environ["NATS_URL"])
    try:
        batch = read("indicator_history", {"currency": "usd", "indicator": "policy_rate"})
        result = await publish(batch, client, "fxmacrodata.usd")
        print(result.messages, "messages in", result.batches, "blocks")
    finally:
        await client.drain()

asyncio.run(main())
```

Pass either a connected `nats.aio.client.Client` or its JetStream context
(`client.jetstream()`). A stream whose subjects cover the destination must
already exist; the destination is a literal subject of dot-separated tokens
(letters, digits, `_`, `-`), and wildcards and URLs are rejected before any
publish. From synchronous code call `publish_sync` or
`publish_operation_sync`, which run the coroutine to completion when no event
loop is running.

Every operation exposed by `fxmacrodata_platform_core.operations()` is
available, including REST and MCP operations. `publish_operation` reads one
operation (in a worker thread, so the event loop stays responsive) and
publishes it in a single call:

```python
from fxmacrodata_nats import publish_operation_sync

publish_operation_sync("release_calendar", {"currency": "usd"}, client, "fxmacrodata.calendar",
                       api_key_env="FXMD_API_KEY")
```

## Message format

Each envelope row becomes one message. The body is canonical UTF-8 JSON with
the keys `operation`, `source_url`, `record_id`, `currency`, `indicator`,
`date`, `announcement_datetime`, `value`, `value_text`, `record_json`,
`response_json` and the publisher's `content_hash` (SHA-256 of the ten source
columns). Only `value` is numeric. Dates and announcement times remain source
strings. No publication time is inferred, and no missing value is filled.
`record_json` retains the original record; `response_json` retains the
complete response, including pagination and metadata. An empty response
produces one message with `record_json` equal to `"null"`, so absence of data
and the server's metadata remain inspectable. It is not an observation.

Headers carry `Nats-Msg-Id` equal to `operation:record_id:content_hash`,
plus `operation`, `record_id`, `content_hash` and `source_url`. The same
source record with the same content always produces the same id, and changed
data or metadata produces a different one.

## Delivery guarantee

Delivery is at-least-once. Messages are published in blocks of `batch_size`
rows (1 to 10,000, 1,000 by default) and every acknowledgement in a block is
awaited before the next block starts. A failed block raises `PublishError`
without the server's own diagnostic text and is not retried; earlier blocks
may already be stored. JetStream drops a repeated `Nats-Msg-Id` inside the
stream's duplicate window (two minutes by default), so a retry within that
window is idempotent; outside it, consumers should deduplicate on the
`Nats-Msg-Id` header. `timeout` bounds each acknowledgement wait in seconds;
`max_message_bytes` (16 MiB by default) rejects an individual envelope larger
than the budget before anything is published. Keep it within the server's
`max_payload`, and narrow the source date range to reduce the response size.
The source response is materialized before publishing; choose a source date
range suitable for memory.

`publish_operation` accepts `api_key_env`, `complete_history`, `max_pages`
and `client_factory` for the public source reader. Supply source credentials
through your runtime secret store, exposing only the environment variable
name; omit `api_key_env` for anonymous USD access. Destination authentication
belongs to the connected client you pass in. The adapter neither saves nor
prints credentials and never places one in a message or header.

The package licence covers this adapter code. FXMacroData data access and
onward redistribution remain subject to your subscription and applicable
licence. Publishing data to a stream does not grant permission to publish or
resell it.

## Development

Tests run offline against an in-memory fake JetStream context:

```sh
python -m pytest tests -q
```

Official SDK reference:
[nats-py JetStream publishing](https://nats-io.github.io/nats.py/modules.html?utm_source=pypi&utm_medium=referral&utm_campaign=nats-fxmacrodata&utm_content=upstream-reference#jetstream).
