DEVX-11247: Add Reports API to the SDK#623
Open
dragonmantank wants to merge 3 commits into
Open
Conversation
- Add ReportsClient with 5 endpoint methods: getRecords, createReport, getReport, cancelReport, downloadReport - Add AsyncReportRequest (POST body), RecordsFilter (GET query params), ReportResponse, RecordsResponse, Product, ReportStatus, ReportsResponseException - Wire ReportsClient into VonageClient - Add 36 unit tests (all passing) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Codecov Report❌ Patch coverage is Additional details and impacted files@@ Coverage Diff @@
## main #623 +/- ##
============================================
- Coverage 99.05% 98.72% -0.33%
- Complexity 3643 3769 +126
============================================
Files 548 556 +8
Lines 8051 8491 +440
Branches 444 452 +8
============================================
+ Hits 7975 8383 +408
- Misses 56 86 +30
- Partials 20 22 +2 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
Contributor
There was a problem hiding this comment.
Pull request overview
Adds first-class support for the Vonage Reports API to the Java SDK, including a new ReportsClient, request/response models, and integration via VonageClient.
Changes:
- Introduces
ReportsClientwith synchronous records retrieval, async report lifecycle (create/status/cancel), and report download. - Adds Reports API models (
Product,ReportStatus,AsyncReportRequest,RecordsFilter,ReportResponse,RecordsResponse) andReportsResponseException. - Adds unit tests for the new client/models and updates
VonageClient+CHANGELOG.
Reviewed changes
Copilot reviewed 12 out of 12 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| src/test/java/com/vonage/client/reports/ReportsClientTest.java | New unit tests for Reports client, enums, request builders, and response parsing. |
| src/main/java/com/vonage/client/VonageClient.java | Wires ReportsClient into the main SDK entrypoint via a new field + getter. |
| src/main/java/com/vonage/client/reports/ReportStatus.java | Adds enum for report processing status with Jackson (de)serialization. |
| src/main/java/com/vonage/client/reports/ReportsResponseException.java | Adds Reports-specific API error exception type. |
| src/main/java/com/vonage/client/reports/ReportsClient.java | Implements Reports API endpoints (records, async reports, cancellation, download). |
| src/main/java/com/vonage/client/reports/ReportResponse.java | Model for async report responses including HAL links and download URL helper. |
| src/main/java/com/vonage/client/reports/RecordsResponse.java | Model for synchronous record retrieval responses with raw record maps. |
| src/main/java/com/vonage/client/reports/RecordsFilter.java | Query-params request builder for synchronous records retrieval filters. |
| src/main/java/com/vonage/client/reports/Product.java | Adds product enum and string mapping for Reports API. |
| src/main/java/com/vonage/client/reports/package-info.java | Package-level documentation for the Reports API module. |
| src/main/java/com/vonage/client/reports/AsyncReportRequest.java | JSON body builder for async report creation. |
| CHANGELOG.md | Notes new Reports API support under Unreleased. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| package com.vonage.client.reports; | ||
|
|
||
| import com.vonage.client.AbstractClientTest; | ||
| import com.vonage.client.TestUtils; |
Comment on lines
+523
to
+528
| public void testDownloadReport() throws Exception { | ||
| byte[] zipData = new byte[]{0x50, 0x4B, 0x03, 0x04}; // PK (zip magic bytes) | ||
| stubResponse(200, new String(zipData)); | ||
| var result = client.downloadReport(FILE_ID); | ||
| assertNotNull(result); | ||
| } |
Comment on lines
+23
to
+30
| * Query parameters for synchronously retrieving report records ({@code GET /v2/reports/records}). | ||
| * <p> | ||
| * Build using {@link #builder(Product, String)}, providing the required {@code product} and | ||
| * {@code account_id}. Use either date-based queries ({@link Builder#dateStart}/{@link Builder#dateEnd}) | ||
| * or ID-based queries ({@link Builder#id}) — when using ID queries, only {@code product}, | ||
| * {@code account_id}, {@code direction}, {@code id}, {@code includeMessage} and | ||
| * {@code showConcatenated} are allowed. | ||
| * </p> |
Comment on lines
+112
to
+118
| * Create an asynchronous report generation request. | ||
| * <p> | ||
| * The report will be processed in the background. Use the returned {@code request_id} to poll | ||
| * for status with {@link #getReport(String)}, and once the status is {@link ReportStatus#SUCCESS}, | ||
| * use the download URL from {@link ReportResponse#getDownloadUrl()} with | ||
| * {@link #downloadReport(String)} to retrieve the data. | ||
| * </p> |
Comment on lines
+187
to
+190
| * The file ID is obtained from {@link ReportResponse#getDownloadUrl()}. | ||
| * </p> | ||
| * | ||
| * @param fileId The UUID of the file to download (from the report's {@code download_report} link). |
- downloadReport now accepts full download URL (from getDownloadUrl()) instead of a bare file ID, matching VoiceClient#downloadRecordingRaw pattern; validates URL is from nexmo.com/vonage.com - Update getDownloadUrl() Javadoc to clarify it returns full absolute URL - Relax RecordsFilter Javadoc to note id-based constraints are API behaviour, not SDK-enforced - Remove unused TestUtils import in ReportsClientTest - Fix testDownloadReport to use ASCII payload with assertArrayEquals - Add testDownloadReportInvalidHost test case Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Revert to constructing the download URL internally from the file ID to prevent open-redirect/SSRF risks. Add ReportResponse#getFileId() as a convenience helper that extracts the UUID from the download_report HAL link, so callers can easily chain getFileId() into downloadReport(). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Implements the Vonage Reports API client for the Java Server SDK.
New
ReportsClientwith 5 methods:getRecords(RecordsFilter)—GET /v2/reports/records(synchronous records retrieval with query params)createReport(AsyncReportRequest)—POST /v2/reports(create asynchronous report)getReport(String reportId)—GET /v2/reports/{reportId}(get async report status)cancelReport(String reportId)—DELETE /v2/reports/{reportId}(cancel async report)downloadReport(String fileId)—GET /v3/media/{file_id}(download report ZIP as bytes)New model classes:
Product— enum of 18 product types (VOICE-CALL, SMS, MESSAGES, etc.)ReportStatus— enum: PENDING, PROCESSING, SUCCESS, ABORTED, FAILED, TRUNCATEDAsyncReportRequest— POST body with all optional product-specific fields, builder patternRecordsFilter— GET query params extendingAbstractQueryParamsRequest, builder patternReportResponse— async operation response with conveniencegetDownloadUrl()RecordsResponse— sync response withList<Map<String, Object>>recordsReportsResponseException— extendsVonageApiResponseExceptionTest coverage:
Jira Ticket
https://jira.vonage.com/browse/DEVX-11247