[javorosas]

Summary

• add URL counterparts to the existing document download methods: downloadPdfUrl, downloadXmlUrl, and downloadZipUrl where each representation is available
• add downloadZipRequestUrl, previewPdfUrl, and previewToInvoicePdfUrl alongside their binary counterparts
• include explicit cancellation-receipt URL methods following the same naming pattern
• expose url, expires_at, content_type, and filename
• correct the existing receipts-to-invoice preview path to match the public API
• validate missing resource IDs before issuing requests
• publish as additive release 5.1.0 when merged

Format compaction remains a concern of the MCP server; the public SDK preserves its established per-operation method design.

Depends on FacturAPI/facturapi#2285. Public API documentation is in FacturAPI/facturapi-docs#299.

Verification

• pnpm run build
• pnpm run test:unit (48 passed: 38 Node + 10 web)
• pnpm run test:types

[Copilot]

🔵 Needs a closer look

Unresolved requests remain for compile-time API assertions and broader PDF/XML/cancellation URL test coverage.

Pull request overview

Adds signed download URL APIs and metadata across invoice, receipt, retention, preview, and ZIP-request resources.

Changes:

• Adds SignedDownloadUrl and URL-based resource methods.
• Corrects the receipts-to-invoice preview endpoint and validates resource IDs.
• Updates tests, documentation, changelog, and version to 5.1.0.

File summaries

File	Summary
test/web/runtime-compat.web.test.ts	Updates the preview endpoint expectation.
test/node/signed-download-urls.node.test.ts	Tests signed URL requests and validation.
test/node/runtime-compat.node.test.ts	Updates the preview endpoint expectation.
test/node/invoices-zip-requests.node.test.ts	Tests ZIP-request URL support.
src/types/common.ts	Defines the SignedDownloadUrl type.
src/resources/retentions.ts	Adds retention URL methods.
src/resources/receipts.ts	Adds receipt URL support and corrects preview routing.
src/resources/invoices.ts	Adds invoice, cancellation, preview, and ZIP-request URL methods.
README.md	Documents signed URL usage.
package.json	Bumps the version to 5.1.0.
CHANGELOG.md	Records the 5.1.0 release changes.

Review details

Suppressed comments (3)

src/types/common.ts:157

• This adds a public SignedDownloadUrl contract, but the repository's compile-time API suite (test-d/runtime-types.test-d.ts) has no assertion for this type or any of the new URL methods. The runtime tests do not verify the generated declaration shape, so a wrong export or return type could still pass test:types; add tsd assertions for SignedDownloadUrl and representative URL methods (including the preview and ZIP-request variants).

export interface SignedDownloadUrl {
  url: string;
  expires_at: string;
  content_type: string;
  filename: string;

test/node/signed-download-urls.node.test.ts:88

• Only retentions.downloadXmlUrl is exercised here; the new PDF and ZIP URL methods are untested, so a typo in either route would not be caught. Add successful-request assertions for all three retention formats, preferably by parameterizing the cases.

    const result = await client.retentions.downloadXmlUrl('ret_123')

test/node/signed-download-urls.node.test.ts:38

• The added suite only exercises downloadZipUrl for invoice downloads, so regressions in the new PDF/XML URL paths—and the successful cancellation XML URL path—would still pass. Add successful-request cases for each newly exposed invoice format (or a table-driven test) with their expected URLs.

    const result = await client.invoices.downloadZipUrl('inv_123')

• Files reviewed: 11/11 changed files
• Comments generated: 0
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.