tres-report-create

# TRES Report Create

You create TRES Finance reports programmatically through the **tres-mcp** MCP server (GraphQL against the BFF). The flow is always: pick the report → trigger the export → poll until `DONE` → return the presigned `link`. Optionally download and analyze the file afterwards.

If you are unsure *which* report the user needs, use the `tres-report-advisor` skill first, then come back here to generate it.

## Workflow

```
- [ ] Step 0: Clarify report type + date range + currency
- [ ] Step 1: Trigger the export (GraphQL via MCP `execute`)
- [ ] Step 1b: If the report isn't in the tables below, derive it from the schema
- [ ] Step 1c: VERIFY a report row was actually created (poll by exact name) — catches silent failures
- [ ] Step 2: Poll the report query until status == DONE
- [ ] Step 3 (optional): Download + analyze the file
```

### Step 0 — Clarify scope (mandatory before triggering)

Confirm before doing anything:

- **Report type (required).** Match the user's wording to the tables below. If unsure, discover what's available:
  ```graphql
  query { availableReportTypes { name exportType entitiesType llmDescription } }
  ```
- **Date range (if applicable).** LEDGER / AUDIT_LOG reports take `timestamp_Gte` / `timestamp_Lte` in ISO 8601:
  - "Q1 2025" → Gte `2025-01-01T00:00:00Z`, Lte `2025-03-31T23:59:59Z`
  - "2025" → Gte `2025-01-01T00:00:00Z`, Lte `2025-12-31T23:59:59Z`
  - If a date range is required and not given, **ask**.
- **Currency.** Default `"usd"` unless the user says otherwise.
- **Analysis goal (only if they want the data analyzed, not just the file).** What should the data answer? Default to a general summary (totals, top items, trends). Drives Step 3.

Confirm briefly, e.g. *"I'll generate a Transaction Ledger for Q1 2025 as CSV. Starting now."*

### Step 1 — Trigger the export

Call the GraphQL query that matches the report's `entitiesType`, passing the export parameters. Run it with the MCP `execute` tool (validate first with `validate_query` if unsure).

**`entitiesType` → query to call**

| entitiesType | Query |
|---|---|
| LEDGER | `transaction` |
| ASSETS | `organizationBalance` |
| BALANCE | `organizationBalance` |
| HISTORICAL_BALANCE | `organizationBalance` |
| ACCOUNTS | `internalAccount` |
| GENERAL | `internalAccount` |
| STAKING_DATA | `stakingYieldRecord` |
| AUDIT_LOG | `auditLog` |
| LOGIN_HISTORY | `loginHistoryExport` |

**Report catalog (`exportFormat` values — verified against prod)**

| Report name | exportFormat | entitiesType |
|---|---|---|
| Transaction Ledger | BASIC_RAW_TRANSACTIONS | LEDGER |
| Realized Gains & Losses | EXTENDED_RAW_TRANSACTIONS | LEDGER |
| Cost Breakdown Raw Transactions | COST_BREAKDOWN_RAW_TRANSACTIONS | LEDGER |
| Rollup Breakdown † | ROLLUP_BREAKDOWN | LEDGER |
| Ledger Reconciliation | RECONCILIATION | LEDGER |
| Cost Basis Roll Forward | COST_BASIS_ROLL_FORWARD | LEDGER |
| Asset Roll Forward | ASSET_ROLL_FORWARD | LEDGER |
| ERP Pre-Sync | PRE_SYNC_JOURNAL | LEDGER |
| ERP Post-Sync | POST_SYNC_JOURNAL | LEDGER |
| MT940 Statement | MT940 | LEDGER |
| Asset Balances | RAW_BALANCES | ASSETS |
| Asset Balances V2 | RAW_BALANCES_V2 | ASSETS |
| Asset Balances - Archives † | ARCHIVED_BALANCES | ASSETS |
| Balance Trends | BALANCE_TRENDS | ASSETS |
| Wallet Balances | INTERNAL_ACCOUNTS_BALANCES | ASSETS |
| Cost Basis Stack Per Asset | COST_BASIS_STACK_PER_ASSET | ASSETS |
| Asset Fiat Values | DAILY_ASSET_PRICING | ASSETS |
| Revaluation Report | REEVALUATION | ASSETS |
| Historical Balance Format | HISTORICAL_BALANCE | HISTORICAL_BALANCE |
| Cost Basis Inventory † | COST_BASIS_INVENTORY | BALANCE |
| Organization Wallets | INTERNAL_ACCOUNTS | ACCOUNTS |
| Contacts | CONTACTS | ACCOUNTS |
| Third Party Addresses | THIRD_PARTY_ADDRESSES | ACCOUNTS |
| Chart of Account | CHART_OF_ACCOUNT | GENERAL |
| ERP Rules | ERP_RULES | GENERAL |
| Connected Custodians | CONNECTED_CUSTODIANS | GENERAL |
| Staking Rewards & Positions | STAKING_DATA | STAKING_DATA |
| Audit Trail / Log | AUDIT_LOG | AUDIT_LOG |
| Login History | LOGIN_HISTORY | LOGIN_HISTORY |

† = special handling (see "Reports needing extra parameters" below). The org catalog evolves — `availableReportTypes` is authoritative. **If a requested report isn't in this table, go to Step 1b and derive it from the schema** rather than guessing.

**Export parameters (always include):**

- `exportFormat` — value from the table above (UPPER_CASE)
- `exportName` — a descriptive, unique name (e.g. `"Transaction Ledger Q1 2025"`) — you'll match on this in Step 2
- `currency` — `"usd"` unless told otherwise
- `outputFormat` — `"CSV"` for downstream analysis, or `"XLSX"` if the user wants a spreadsheet

Add `timestamp_Gte` / `timestamp_Lte` for date-ranged reports (LEDGER, AUDIT_LOG).

> ### ⚠️ GraphQL variable types — get these EXACTLY right (first-run correctness)
>
> The BFF **strictly validates variable types**. A wrong type returns HTTP 400 and **no report is created** — and the `execute` tool surfaces this under an `error` / `error_type` field, *not* the GraphQL `errors` array, so it is easy to miss. Declare variables with these exact types:
>
> | Variable | GraphQL type | Notes |
> |---|---|---|
> | `exportFormat` | `String` | the UPPER_CASE value |
> | `exportName` | `String` | unique name |
> | `currency` | `String` | e.g. `"usd"` |
> | `outputFormat` | **`ReportOutputFormat`** | NOT `String`. Value `"CSV"` / `"XLSX"` |
> | `timestamp_Gte` / `timestamp_Lte` | **`DateTime`** | NOT `String`. ISO 8601 value |
> | `identifier_In`, `children_Asset_AssetClass_In`, `children_BelongsTo_In` | **`[String]`** | NOT `[ID]` |
>
> The params must be passed as **variables named exactly** `exportName`, `exportFormat`, etc. — the BFF reads them from `info.variable_values` by name. Inline literals or renamed variables (`$ef`) silently create **no** report.

Example — trigger a Transaction Ledger export (verified working form):

```graphql
query($limit: Int, $offset: Int,