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

# FXMacroData for Apache NiFi

`FetchFXMacroData` is an Apache NiFi 2 Python processor that fetches one
FXMacroData operation per trigger and emits a FlowFile with the complete
response. Route macro announcements, release calendars, FX, commodities and
positioning data into any NiFi flow without writing an HTTP client.

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

## Install

Requires Apache NiFi 2.0 or later with Python processors enabled
(`nifi.python.command` in `nifi.properties`) and Python 3.10 or later on the
NiFi host. Copy `src/fxmacrodata_nifi/FetchFXMacroData.py` into NiFi's
Python extensions directory (`python_extensions/` by default). The processor
declares `fxmacrodata-platform-core==0.1.0` as its dependency; make that
package and its adjacent `fxmacrodata-public-client` available to NiFi's
Python environment from the distribution supplied to you, for example by
pointing NiFi's `pip` index at a local directory that contains both, or by
installing them into the interpreter NiFi uses:

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

NiFi supplies the `nifiapi` module at run time. The package carries a small
`_shim` module with the same names so the processor can be imported and
tested outside NiFi; it is never used inside NiFi.

## Configure

Add `FetchFXMacroData` to the canvas and set its properties:

| Property | Description |
| --- | --- |
| Operation | One of the 87 documented operations; MCP tools carry an `mcp_` prefix. |
| Arguments | JSON object of operation arguments, for example `{"currency": "usd", "indicator": "policy_rate"}`. |
| API Key Env | Name of the environment variable holding your API key (for example `FXMD_API_KEY`). Leave empty for anonymous access. |
| Complete History | `true` follows every page of a historical operation; `false` fetches the supplied page only. |
| Max Pages | Upper bound on pages followed for a complete history (default 10000). |

USD data works without a key: Operation `indicator_history`, Arguments
`{"currency": "usd", "indicator": "policy_rate"}`. Schedule the processor
with a timer or cron run schedule.

## Credentials

Set the API key in the environment of the NiFi process (or its Python
sub-process) and give the processor only the variable's name. The processor
resolves the value at run time, never stores it in the flow definition and
never writes it to attributes, content or logs. Arguments carrying `api_key`,
tokens, URLs or endpoint overrides are rejected before any request.

## FlowFile output

Each successful trigger routes one FlowFile to `success` with content

```json
{"operation": "indicator_history", "source_url": "<publisher URL>", "rows": [...]}
```

and attributes `mime.type`, `fxmacrodata.operation`,
`fxmacrodata.source_url`, `fxmacrodata.row_count` and
`fxmacrodata.complete_history`. Each row carries `operation`, `source_url`,
`record_id`, `currency`, `indicator`, `date`, `announcement_datetime`,
`value`, `value_text`, `record_json` and `response_json`. Only `value` is
numeric (nullable); every other field is a nullable string. `record_json`
retains the original record and `response_json` the complete response,
including pagination and revision metadata. An empty response produces one
row with `record_json` of `null`; it is not an observation. Dates and
announcement times remain source strings, no publication time is inferred
and no missing value is filled. `record_id` is a stable hash of the
operation and record, so repeated fetches of unchanged data produce the same
identifiers.

Invalid configuration or a failed read routes one FlowFile to `failure`
with a `fxmacrodata.error` attribute and a JSON `{"error": ...}` body. The
message never contains credentials or upstream diagnostics.

## Delivery guarantee

Each trigger performs one fresh read; the processor keeps no state. Delivery
into your flow is at-least-once per schedule. Deduplicate downstream on
`operation` and `record_id` (for example with `DetectDuplicate` or a
`MERGE` in your sink) when a sink requires exactly-once storage.

## Development

Run the offline tests with `python -m pytest tests -q`. They instantiate the
processor with the shim, fake the NiFi context and monkeypatch the public
reader; they never call the live service.
