starred/App-Store-Connect-CLI
1
0
Fork 0
mirror of https://github.com/rudrankriyam/App-Store-Connect-CLI.git synced 2026-04-25 23:55:51 +03:00
Code Issues 2 Projects Releases 10 Packages Wiki Activity

[GH-ISSUE #68] Add Payments & Financial Reports (financeReports) support #15

New issue
Closed
opened 2026-02-26 21:32:47 +03:00 by kerem · 3 comments
kerem commented 2026-02-26 21:32:47 +03:00
Owner
Copy link

Originally created by @rudrankriyam on GitHub (Jan 24, 2026).
Original GitHub issue: https://github.com/rudrankriyam/App-Store-Connect-CLI/issues/68

Summary

Add Payments & Financial Reports support via the App Store Connect API. ASC currently covers App Analytics + Sales & Trends, but does not support financeReports (payments/proceeds). This blocks automation of monthly financial reports.

Current State (verified)

  • No existing payments/financial reports code, flags, or docs in the repo.
  • Repo search (rg -n "payment|payments|financial|finance|payout|proceeds|tax|bank|transfer|statement" -S internal cmd README.md) returns no matches.

Why this matters

  • Financial reports are monthly (Apple fiscal calendar), available around the first Friday of the next fiscal month, and retained for 10 years.
  • Apple supports automation via the App Store Connect API for financial reports.

Official References

API Details (from Apple OpenAPI spec)

Endpoint: GET /v1/financeReports

Required filters

  • filter[vendorNumber] (array of string)
  • filter[reportType] (array of string)
  • filter[regionCode] (array of string)
  • filter[reportDate] (array of string)

reportType enum

  • FINANCIAL
  • FINANCE_DETAIL

Response

  • 200 returns application/a-gzip (gzip payload)
  • Errors: 400, 401, 403, 429

Open Questions / Reconciliation

Apple’s Help docs list 4 UI report types:

  • All Countries or Regions (Detailed)
  • All Countries or Regions (Single File)
  • All Countries or Regions (Multiple Files)
  • Transaction Tax (Single File)

But the API exposes only FINANCIAL and FINANCE_DETAIL. Need to confirm:

  • Which UI types map to FINANCIAL vs FINANCE_DETAIL
  • Whether Transaction Tax is available via API (and if so, what reportType or filters apply)

Proposed CLI Design

Add a new command group:

asc finance reports --vendor "12345678" --report-type FINANCIAL --region "US" --date "2025-12"

Flags (explicit, no short flags):

  • --vendor (required, fallback ASC_VENDOR_NUMBER)
  • --report-type (required; FINANCIAL | FINANCE_DETAIL)
  • --region (required; regionCode)
  • --date (required; YYYY-MM)
  • --output (optional; default: finance_report_{date}_{type}_{region}.tsv.gz)
  • --decompress (optional; write .tsv)
  • --output-format (json|table|markdown for metadata)
  • --pretty (JSON only)

JSON output example:

{
  "file": "reports/finance_report_2025-12_FINANCIAL_US.tsv.gz",
  "decompressedFile": "reports/finance_report_2025-12_FINANCIAL_US.tsv",
  "vendorNumber": "12345678",
  "reportType": "FINANCIAL",
  "regionCode": "US",
  "reportDate": "2025-12",
  "bytes": 123456
}

Implementation Plan

  1. internal/asc/finance.go
  • Add FinanceReportType enum.
  • Add params struct + DownloadFinanceReport method.
  • Build query with required filters.
  • Use doStream with Accept: application/a-gzip.
  1. cmd/finance.go
  • New finance command group with reports subcommand.
  • Validate: required flags, enum checks, date format (YYYY-MM).
  • Safe file creation via openNewFileNoFollow.
  • Optional decompress (reuse analytics helpers).
  1. Tests
  • CLI validation tests (missing flags, invalid reportType, bad date).
  • Client HTTP tests (query params, Accept header).
  • Download + decompress tests (gzip handling).
  1. Docs
  • README command list + examples.
  • Help text includes role requirements (Account Holder/Admin/Finance).

Acceptance Criteria

  • asc finance reports downloads .gz correctly and prints metadata JSON.
  • --decompress writes .tsv and reports both paths.
  • Errors are explicit and exit non‑zero; no silent failures.
Originally created by @rudrankriyam on GitHub (Jan 24, 2026). Original GitHub issue: https://github.com/rudrankriyam/App-Store-Connect-CLI/issues/68 ## Summary Add Payments & Financial Reports support via the App Store Connect API. ASC currently covers App Analytics + Sales & Trends, but **does not support financeReports** (payments/proceeds). This blocks automation of monthly financial reports. ## Current State (verified) - No existing payments/financial reports code, flags, or docs in the repo. - Repo search (`rg -n "payment|payments|financial|finance|payout|proceeds|tax|bank|transfer|statement" -S internal cmd README.md`) returns no matches. ## Why this matters - Financial reports are **monthly** (Apple fiscal calendar), available around the **first Friday** of the next fiscal month, and retained for **10 years**. - Apple supports **automation via the App Store Connect API** for financial reports. ## Official References - API Overview + OpenAPI spec download: https://developer.apple.com/app-store-connect/api/ - Download financial reports: https://developer.apple.com/help/app-store-connect/getting-paid/download-financial-reports/ - Financial report fields reference: https://developer.apple.com/help/app-store-connect/reference/reporting/financial-report-fields/ - Reporting tools overview (mentions API automation): https://developer.apple.com/help/app-store-connect/measure-app-performance/overview-of-reporting-tools ## API Details (from Apple OpenAPI spec) **Endpoint**: `GET /v1/financeReports` **Required filters** - `filter[vendorNumber]` (array of string) - `filter[reportType]` (array of string) - `filter[regionCode]` (array of string) - `filter[reportDate]` (array of string) **reportType enum** - `FINANCIAL` - `FINANCE_DETAIL` **Response** - `200` returns `application/a-gzip` (gzip payload) - Errors: `400`, `401`, `403`, `429` ## Open Questions / Reconciliation Apple’s Help docs list 4 UI report types: - All Countries or Regions (Detailed) - All Countries or Regions (Single File) - All Countries or Regions (Multiple Files) - Transaction Tax (Single File) But the API exposes only `FINANCIAL` and `FINANCE_DETAIL`. Need to confirm: - Which UI types map to `FINANCIAL` vs `FINANCE_DETAIL` - Whether Transaction Tax is available via API (and if so, what `reportType` or filters apply) ## Proposed CLI Design Add a new command group: ``` asc finance reports --vendor "12345678" --report-type FINANCIAL --region "US" --date "2025-12" ``` Flags (explicit, no short flags): - `--vendor` (required, fallback `ASC_VENDOR_NUMBER`) - `--report-type` (required; FINANCIAL | FINANCE_DETAIL) - `--region` (required; regionCode) - `--date` (required; YYYY-MM) - `--output` (optional; default: `finance_report_{date}_{type}_{region}.tsv.gz`) - `--decompress` (optional; write .tsv) - `--output-format` (json|table|markdown for metadata) - `--pretty` (JSON only) JSON output example: ```json { "file": "reports/finance_report_2025-12_FINANCIAL_US.tsv.gz", "decompressedFile": "reports/finance_report_2025-12_FINANCIAL_US.tsv", "vendorNumber": "12345678", "reportType": "FINANCIAL", "regionCode": "US", "reportDate": "2025-12", "bytes": 123456 } ``` ## Implementation Plan 1) `internal/asc/finance.go` - Add `FinanceReportType` enum. - Add params struct + `DownloadFinanceReport` method. - Build query with required filters. - Use `doStream` with `Accept: application/a-gzip`. 2) `cmd/finance.go` - New `finance` command group with `reports` subcommand. - Validate: required flags, enum checks, date format (YYYY-MM). - Safe file creation via `openNewFileNoFollow`. - Optional decompress (reuse analytics helpers). 3) Tests - CLI validation tests (missing flags, invalid reportType, bad date). - Client HTTP tests (query params, Accept header). - Download + decompress tests (gzip handling). 4) Docs - README command list + examples. - Help text includes role requirements (Account Holder/Admin/Finance). ## Acceptance Criteria - `asc finance reports` downloads `.gz` correctly and prints metadata JSON. - `--decompress` writes `.tsv` and reports both paths. - Errors are explicit and exit non‑zero; no silent failures.
kerem closed this issue 2026-02-26 21:32:47 +03:00
kerem commented 2026-02-26 21:32:48 +03:00
Author
Owner
Copy link

@rudrankriyam commented on GitHub (Jan 24, 2026):

@cursor please implement this issue. Follow the implementation plan and acceptance criteria in the issue description.

<!-- gh-comment-id:3794439929 --> @rudrankriyam commented on GitHub (Jan 24, 2026): @cursor please implement this issue. Follow the implementation plan and acceptance criteria in the issue description.
kerem commented 2026-02-26 21:32:48 +03:00
Author
Owner
Copy link

@cursor[bot] commented on GitHub (Jan 24, 2026):

Summary:

  • Added finance report client support and asc finance reports CLI with validation, gzip download/decompress, and metadata output formatting.
  • Wired finance report output rendering (JSON/table/markdown) and README docs with usage/notes.
  • Added tests for finance query building, download headers, CLI validation, and output formatting.

Tests:

  • PATH="$(go env GOPATH)/bin:$PATH" make format
  • PATH="$(go env GOPATH)/bin:$PATH" make lint
  • PATH="$(go env GOPATH)/bin:$PATH" make test

Notes:

  • Installed gofumpt via go install mvdan.cc/gofumpt@latest to satisfy make format and ran the format/lint/test targets with GOPATH/bin on PATH.

View PR
Open in Cursor Open in Web

<!-- gh-comment-id:3794440004 --> @cursor[bot] commented on GitHub (Jan 24, 2026): Summary: - Added finance report client support and `asc finance reports` CLI with validation, gzip download/decompress, and metadata output formatting. - Wired finance report output rendering (JSON/table/markdown) and README docs with usage/notes. - Added tests for finance query building, download headers, CLI validation, and output formatting. Tests: - `PATH="$(go env GOPATH)/bin:$PATH" make format` - `PATH="$(go env GOPATH)/bin:$PATH" make lint` - `PATH="$(go env GOPATH)/bin:$PATH" make test` Notes: - Installed `gofumpt` via `go install mvdan.cc/gofumpt@latest` to satisfy `make format` and ran the format/lint/test targets with GOPATH/bin on PATH. <a href="https://github.com/rudrankriyam/App-Store-Connect-CLI/pull/79"><picture><source media="(prefers-color-scheme: dark)" srcset="https://cursor.com/view-pr-dark.svg"><source media="(prefers-color-scheme: light)" srcset="https://cursor.com/view-pr-light.svg"><img alt="View PR" src="https://cursor.com/view-pr-light.svg"></picture></a> <a href="https://cursor.com/background-agent?bcId=bc-fcff6d6e-2f9f-4d21-b83e-ff877ae93aba"><picture><source media="(prefers-color-scheme: dark)" srcset="https://cursor.com/open-in-cursor-dark.svg"><source media="(prefers-color-scheme: light)" srcset="https://cursor.com/open-in-cursor-light.svg"><img alt="Open in Cursor" src="https://cursor.com/open-in-cursor.svg"></picture></a>&nbsp;<a href="https://cursor.com/agents?id=bc-fcff6d6e-2f9f-4d21-b83e-ff877ae93aba"><picture><source media="(prefers-color-scheme: dark)" srcset="https://cursor.com/open-in-web-dark.svg"><source media="(prefers-color-scheme: light)" srcset="https://cursor.com/open-in-web-light.svg"><img alt="Open in Web" src="https://cursor.com/open-in-web.svg"></picture></a>
kerem commented 2026-02-26 21:32:48 +03:00
Author
Owner
Copy link

@rudrankriyam commented on GitHub (Jan 24, 2026):

This has been implemented. The asc finance reports command supports all proposed functionality:

  • --vendor (with ASC_VENDOR_NUMBER fallback)
  • --report-type (FINANCIAL | FINANCE_DETAIL)
  • --region
  • --date (YYYY-MM format)
  • --output (custom file path)
  • --decompress (writes .tsv)
  • --output-format (json/table/markdown for metadata)
  • --pretty (JSON formatting)

Documentation added in PR #89 and API notes in PR #94.

<!-- gh-comment-id:3794792174 --> @rudrankriyam commented on GitHub (Jan 24, 2026): This has been implemented. The `asc finance reports` command supports all proposed functionality: - `--vendor` (with `ASC_VENDOR_NUMBER` fallback) - `--report-type` (FINANCIAL | FINANCE_DETAIL) - `--region` - `--date` (YYYY-MM format) - `--output` (custom file path) - `--decompress` (writes .tsv) - `--output-format` (json/table/markdown for metadata) - `--pretty` (JSON formatting) Documentation added in PR #89 and API notes in PR #94.
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
1.2.6
1.2.5
1.2.4
1.2.3
1.2.2
1.2.1
1.2.0
1.1.1
1.1.0
1.0.1
1.0.0
0.49.1
0.49.0
0.48.1
0.48.0
0.47.1
0.47.0
0.46.2
0.46.1
0.46.0
0.45.4
0.45.3
0.45.2
0.45.1
0.45.0
0.44.2
0.44.1
0.44.0
0.43.0
0.42.0
0.41.4
0.41.3
0.41.2
0.41.1
0.41.0
0.40.1
0.40.0
0.39.1
0.39.0
0.38.3
0.38.2
0.38.1
0.38.0
0.37.3
0.37.2
0.37.1
0.37.0
0.36.3
0.36.2
0.36.1
0.36.0
0.35.3
0.35.2
0.35.1
0.35.0
0.34.1
0.34.0
0.33.2
0.33.1
0.33.0
0.32.0
0.31.3
0.31.2
0.31.1
0.31.0
0.30.0
0.29.3
0.29.2
0.29.1
0.29.0
0.28.14
0.28.13
0.28.12
0.28.11
0.28.10
0.28.9
0.28.8
0.28.7
0.28.6
0.28.5
0.28.4
0.28.3
0.28.2
0.28.1
0.28.0
0.27.0
0.26.4
0.26.3
0.26.2
0.26.1
0.26.0
0.25.4
0.25.3
0.25.1
0.25.0
0.24.3
0.24.2
0.24.1
0.24.0
0.23.5
0.23.4
0.23.3
0.23.2
0.23.1
0.23.0
0.22.1
0.22.0
0.21.0
0.20.2
0.20.1
0.20.0
0.19.3
0.19.2
0.19.1
0.19.0
0.18.2
0.18.1
0.18.0
0.17.0
0.16.0
0.15.0
0.14.0
0.13.0
0.12.4
0.12.3
0.12.2
0.12.1
0.12.0
0.11.0
0.10.2
0.10.1
0.10.0
0.9.0
0.8.1
0.8.0
0.7.0
0.6.0
0.5.0
0.3.1
0.3.0
0.2.0
0.1.6
0.1.5
0.1.4
0.1.3
0.1.2
0.1.1
0.1.0
Labels
Clear labels   
bug

   
bug

   
documentation

   
enhancement

   
pull-request

Mirrored from GitHub Pull Request

No labels
bug
bug
documentation
enhancement
pull-request
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
starred/App-Store-Connect-CLI#15
No description provided.