feat: launch Java SDK foundation with typed complement models

[javorosas]

Summary

• bootstrap the official io.facturapi Java SDK with bearer auth and resource clients
• add typed response models across core resources and tools
• add deep complement typing for pago, nomina, carta_porte, and comercio_exterior
• add CI workflow for pushes to main and pull requests
• add and adjust tests and README consumer docs

Verification

• mvn -q -Dmaven.repo.local=.m2/repository test

[Copilot]

Pull request overview

Bootstraps the io.facturapi Java SDK with typed resource clients, typed response models (including deep CFDI complement typing), updated tests, and updated consumer documentation.

Changes:

• Migrates the SDK surface from untyped JsonNode responses to typed models across core resources/tools.
• Adds deep complement parsing/typing for pago, nomina, carta_porte, and comercio_exterior.
• Reworks tests to use a JDK HttpClient stub (removing MockWebServer dependency) and updates README/pom metadata.

Reviewed changes

Copilot reviewed 143 out of 144 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/test/java/io/facturapi/WebhooksResourceTest.java	Updates webhook signature test to use typed ApiEvent and io.facturapi packages.
src/test/java/io/facturapi/StubHttpClient.java	Adds a lightweight HttpClient stub for unit tests.
src/test/java/io/facturapi/FacturapiResourcesTest.java	Adds tests for request paths, typed organization API keys, and typed complements.
src/test/java/io/facturapi/FacturapiHttpClientTest.java	Adds tests for bearer auth, typed JSON parsing, binary downloads, and error handling.
src/test/java/com/facturapi/FacturapiResourcesTest.java	Removes legacy tests using MockWebServer + untyped JsonNode.
src/test/java/com/facturapi/FacturapiHttpClientTest.java	Removes legacy tests using MockWebServer + untyped JsonNode.
src/main/java/io/facturapi/tools/ToolsResource.java	Introduces typed tools resource (TaxInfoValidation).
src/main/java/io/facturapi/tools/ComercioExteriorCatalogsTool.java	Adds typed Comercio Exterior catalogs tool (SearchResult<CatalogItem>).
src/main/java/io/facturapi/tools/CatalogsTool.java	Adds typed SAT catalogs tool (SearchResult<CatalogItem>).
src/main/java/io/facturapi/tools/CartaPorteCatalogsTool.java	Adds typed Carta Porte catalogs tool with shared helper.
src/main/java/io/facturapi/resources/WebhooksResource.java	Adds typed webhooks resource + signature validation returning ApiEvent.
src/main/java/io/facturapi/resources/RetentionsResource.java	Adds typed retentions resource + PDF/XML/ZIP downloads.
src/main/java/io/facturapi/resources/ReceiptsResource.java	Adds typed receipts resource + invoice/global invoice helpers.
src/main/java/io/facturapi/resources/ProductsResource.java	Adds typed products CRUD resource.
src/main/java/io/facturapi/resources/InvoicesResource.java	Adds typed invoices resource + downloads, draft operations, preview PDF.
src/main/java/io/facturapi/resources/CustomersResource.java	Adds typed customers CRUD resource + validation/email helper.
src/main/java/io/facturapi/resources/BaseResource.java	Adds typed base resource helpers for class/type-ref responses.
src/main/java/io/facturapi/resources/OrganizationsResource.java	Adds typed organizations resource including multipart uploads + team/roles APIs.
src/main/java/io/facturapi/models/XmlNamespace.java	New typed model.
src/main/java/io/facturapi/models/Webhook.java	New typed model.
src/main/java/io/facturapi/models/TaxInfoValidationError.java	New typed model.
src/main/java/io/facturapi/models/TaxInfoValidation.java	New typed model (aliases valid/is_valid).
src/main/java/io/facturapi/models/Tax.java	New typed model.
src/main/java/io/facturapi/models/Stamp.java	New typed model.
src/main/java/io/facturapi/models/Series.java	New typed model.
src/main/java/io/facturapi/models/SelfInvoiceSettings.java	New typed model.
src/main/java/io/facturapi/models/SearchResult.java	New generic typed pagination model.
src/main/java/io/facturapi/models/RetentionTotals.java	New typed model.
src/main/java/io/facturapi/models/RetentionRetainedTax.java	New typed model.
src/main/java/io/facturapi/models/RetentionPeriod.java	New typed model.
src/main/java/io/facturapi/models/Retention.java	New typed model.
src/main/java/io/facturapi/models/RelatedDocument.java	New typed model.
src/main/java/io/facturapi/models/ReceiptSettings.java	New typed model.
src/main/java/io/facturapi/models/Receipt.java	New typed model.
src/main/java/io/facturapi/models/ProductInfo.java	New typed model.
src/main/java/io/facturapi/models/Product.java	New typed model.
src/main/java/io/facturapi/models/PendingPlanUpdate.java	New typed model.
src/main/java/io/facturapi/models/PdfExtra.java	New typed model.
src/main/java/io/facturapi/models/PaymentRelated.java	New typed model.
src/main/java/io/facturapi/models/Payment.java	New typed model.
src/main/java/io/facturapi/models/OrganizationUserAccess.java	New typed model.
src/main/java/io/facturapi/models/OrganizationTeamRoleTemplate.java	New typed model.
src/main/java/io/facturapi/models/OrganizationTeamRole.java	New typed model.
src/main/java/io/facturapi/models/OrganizationInvite.java	New typed model.
src/main/java/io/facturapi/models/Organization.java	New typed model.
src/main/java/io/facturapi/models/LocalTax.java	New typed model.
src/main/java/io/facturapi/models/Legal.java	New typed model.
src/main/java/io/facturapi/models/InvoiceItemThirdParty.java	New typed model.
src/main/java/io/facturapi/models/InvoiceItemPart.java	New typed model.
src/main/java/io/facturapi/models/InvoiceItem.java	New typed model.
src/main/java/io/facturapi/models/InvoiceCancellation.java	New typed model.
src/main/java/io/facturapi/models/GlobalInfo.java	New typed model.
src/main/java/io/facturapi/models/GenericResponse.java	New typed model.
src/main/java/io/facturapi/models/DomainAvailability.java	New typed model.
src/main/java/io/facturapi/models/Customization.java	New typed model.
src/main/java/io/facturapi/models/CustomerInfo.java	New typed model.
src/main/java/io/facturapi/models/Customer.java	New typed model.
src/main/java/io/facturapi/models/CompletionStep.java	New typed model.
src/main/java/io/facturapi/models/CatalogItem.java	New typed model.
src/main/java/io/facturapi/models/Certificate.java	New typed model.
src/main/java/io/facturapi/models/ApiKey.java	New typed model.
src/main/java/io/facturapi/models/ApiEventData.java	New typed model.
src/main/java/io/facturapi/models/ApiEvent.java	New typed model.
src/main/java/io/facturapi/models/Address.java	New typed model.
src/main/java/io/facturapi/models/complements/pago/PaymentRelatedDocumentTax.java	New typed pago complement model.
src/main/java/io/facturapi/models/complements/pago/PaymentRelatedDocument.java	New typed pago complement model.
src/main/java/io/facturapi/models/complements/pago/PagoComplementData.java	New typed pago complement model.
src/main/java/io/facturapi/models/complements/nomina/NominaSubcontratacion.java	New typed nómina complement model.
src/main/java/io/facturapi/models/complements/nomina/NominaSeparacion.java	New typed nómina complement model.
src/main/java/io/facturapi/models/complements/nomina/NominaReceptor.java	New typed nómina complement model.
src/main/java/io/facturapi/models/complements/nomina/NominaPercepciones.java	New typed nómina complement model.
src/main/java/io/facturapi/models/complements/nomina/NominaPercepcion.java	New typed nómina complement model.
src/main/java/io/facturapi/models/complements/nomina/NominaOtroPago.java	New typed nómina complement model.
src/main/java/io/facturapi/models/complements/nomina/NominaJubilacion.java	New typed nómina complement model.
src/main/java/io/facturapi/models/complements/nomina/NominaIncapacidad.java	New typed nómina complement model.
src/main/java/io/facturapi/models/complements/nomina/NominaHorasExtra.java	New typed nómina complement model.
src/main/java/io/facturapi/models/complements/nomina/NominaEntidadSncf.java	New typed nómina complement model.
src/main/java/io/facturapi/models/complements/nomina/NominaEmisor.java	New typed nómina complement model.
src/main/java/io/facturapi/models/complements/nomina/NominaDeduccion.java	New typed nómina complement model.
src/main/java/io/facturapi/models/complements/nomina/NominaComplementData.java	New typed nómina complement model.
src/main/java/io/facturapi/models/complements/nomina/NominaCompensacion.java	New typed nómina complement model.
src/main/java/io/facturapi/models/complements/nomina/NominaAcciones.java	New typed nómina complement model.
src/main/java/io/facturapi/models/complements/InvoiceComplement.java	Adds dynamic complement typing/parsing over raw data.
src/main/java/io/facturapi/models/complements/comercio_exterior/ComercioExteriorReceptorRef.java	New typed Comercio Exterior complement model.
src/main/java/io/facturapi/models/complements/comercio_exterior/ComercioExteriorPartyRef.java	New typed Comercio Exterior complement model.
src/main/java/io/facturapi/models/complements/comercio_exterior/ComercioExteriorMercancias.java	New typed Comercio Exterior complement model.
src/main/java/io/facturapi/models/complements/comercio_exterior/ComercioExteriorMercancia.java	New typed Comercio Exterior complement model.
src/main/java/io/facturapi/models/complements/comercio_exterior/ComercioExteriorEmisor.java	New typed Comercio Exterior complement model.
src/main/java/io/facturapi/models/complements/comercio_exterior/ComercioExteriorDomicilio.java	New typed Comercio Exterior complement model.
src/main/java/io/facturapi/models/complements/comercio_exterior/ComercioExteriorDestinatarioRef.java	New typed Comercio Exterior complement model.
src/main/java/io/facturapi/models/complements/comercio_exterior/ComercioExteriorDescripcionesEspecificas.java	New typed Comercio Exterior complement model.
src/main/java/io/facturapi/models/complements/comercio_exterior/ComercioExteriorComplementData.java	New typed Comercio Exterior complement model (boolean-or-object Emisor).
src/main/java/io/facturapi/models/complements/carta_porte/CartaPorteUbicacion.java	New typed Carta Porte complement model.
src/main/java/io/facturapi/models/complements/carta_porte/CartaPorteTransporteMaritimo.java	New typed Carta Porte complement model.
src/main/java/io/facturapi/models/complements/carta_porte/CartaPorteTransporteFerroviario.java	New typed Carta Porte complement model.
src/main/java/io/facturapi/models/complements/carta_porte/CartaPorteTransporteAereo.java	New typed Carta Porte complement model.
src/main/java/io/facturapi/models/complements/carta_porte/CartaPorteSeguros.java	New typed Carta Porte complement model.
src/main/java/io/facturapi/models/complements/carta_porte/CartaPorteRemolqueCcp.java	New typed Carta Porte complement model.
src/main/java/io/facturapi/models/complements/carta_porte/CartaPorteRemolque.java	New typed Carta Porte complement model.
src/main/java/io/facturapi/models/complements/carta_porte/CartaPorteParteTransporte.java	New typed Carta Porte complement model.
src/main/java/io/facturapi/models/complements/carta_porte/CartaPorteMercancias.java	New typed Carta Porte complement model.
src/main/java/io/facturapi/models/complements/carta_porte/CartaPorteIdentificacionVehicular.java	New typed Carta Porte complement model.
src/main/java/io/facturapi/models/complements/carta_porte/CartaPorteGuiaIdentificacion.java	New typed Carta Porte complement model.
src/main/java/io/facturapi/models/complements/carta_porte/CartaPorteFiguraTransporte.java	New typed Carta Porte complement model.
src/main/java/io/facturapi/models/complements/carta_porte/CartaPorteDomicilio.java	New typed Carta Porte complement model.
src/main/java/io/facturapi/models/complements/carta_porte/CartaPorteDocumentacionAduanera.java	New typed Carta Porte complement model.
src/main/java/io/facturapi/models/complements/carta_porte/CartaPorteDetalleMercancia.java	New typed Carta Porte complement model.
src/main/java/io/facturapi/models/complements/carta_porte/CartaPorteDerechosDePaso.java	New typed Carta Porte complement model.
src/main/java/io/facturapi/models/complements/carta_porte/CartaPorteContenedorMaritimo.java	New typed Carta Porte complement model.
src/main/java/io/facturapi/models/complements/carta_porte/CartaPorteContenedorFerroviario.java	New typed Carta Porte complement model.
src/main/java/io/facturapi/models/complements/carta_porte/CartaPorteComplementData.java	New typed Carta Porte complement model.
src/main/java/io/facturapi/models/complements/carta_porte/CartaPorteCarroFerroviario.java	New typed Carta Porte complement model.
src/main/java/io/facturapi/models/complements/carta_porte/CartaPorteCantidadTransporta.java	New typed Carta Porte complement model.
src/main/java/io/facturapi/models/complements/carta_porte/CartaPorteAutotransporte.java	New typed Carta Porte complement model.
src/main/java/io/facturapi/http/MultipartBodyBuilder.java	Moves multipart utilities to io.facturapi.http.
src/main/java/io/facturapi/http/MultipartBody.java	Moves multipart utilities to io.facturapi.http.
src/main/java/io/facturapi/http/FacturapiHttpClient.java	Reworks HTTP client to typed get/post/put/delete with conversion helpers.
src/main/java/io/facturapi/http/FacturapiConfig.java	Simplifies config construction and defaults (API version, mapper).
src/main/java/io/facturapi/FacturapiException.java	Moves exception to io.facturapi and keeps status/body accessors.
src/main/java/io/facturapi/Facturapi.java	Rebuilds SDK entrypoint using typed resources/tools under io.facturapi.
src/main/java/io/facturapi/enums/TaxType.java	Moves enum to io.facturapi.enums.
src/main/java/io/facturapi/enums/TaxFactor.java	Moves enum to io.facturapi.enums.
src/main/java/io/facturapi/enums/PaymentForm.java	Moves enum to io.facturapi.enums.
src/main/java/io/facturapi/enums/InvoiceType.java	Moves enum to io.facturapi.enums.
src/main/java/io/facturapi/enums/CancellationMotive.java	Moves enum to io.facturapi.enums.
src/main/java/io/facturapi/constants/FacturapiConstants.java	Moves constants to io.facturapi.constants.
src/main/java/io/facturapi/ApiVersion.java	Moves API version enum to io.facturapi.
src/main/java/com/facturapi/tools/ToolsResource.java	Removes legacy untyped tools resource.
src/main/java/com/facturapi/tools/ComercioExteriorCatalogsTool.java	Removes legacy untyped catalogs tool.
src/main/java/com/facturapi/tools/CatalogsTool.java	Removes legacy untyped catalogs tool.
src/main/java/com/facturapi/tools/CartaPorteCatalogsTool.java	Removes legacy untyped catalogs tool.
src/main/java/com/facturapi/resources/WebhooksResource.java	Removes legacy untyped webhooks resource.
src/main/java/com/facturapi/resources/RetentionsResource.java	Removes legacy untyped retentions resource.
src/main/java/com/facturapi/resources/ReceiptsResource.java	Removes legacy untyped receipts resource.
src/main/java/com/facturapi/resources/ProductsResource.java	Removes legacy untyped products resource.
src/main/java/com/facturapi/resources/OrganizationsResource.java	Removes legacy untyped organizations resource.
src/main/java/com/facturapi/resources/InvoicesResource.java	Removes legacy untyped invoices resource.
src/main/java/com/facturapi/resources/CustomersResource.java	Removes legacy untyped customers resource.
src/main/java/com/facturapi/resources/BaseResource.java	Removes legacy untyped base resource.
README.md	Updates consumer docs for new groupId/package and typed usage examples.
pom.xml	Updates versioning and removes OkHttp MockWebServer test dependency.
.gitignore	Adds standard ignores for build artifacts, local .m2, IDE/OS files.

Comments suppressed due to low confidence (3)

src/main/java/io/facturapi/http/FacturapiHttpClient.java:105

• requestJsonNode returns nullNode() when the response body is empty. When callers request a typed response (e.g., GenericResponse.class), convertValue(NullNode, ...) can yield null, which is a surprising behavior change and can cause NPEs for endpoints that legitimately return 204/empty bodies (common for DELETE/PUT operations). Consider returning an empty object node instead, or special-casing empty bodies to return null only when responseType is Void (or otherwise documenting/handling this consistently).
  src/main/java/io/facturapi/http/FacturapiConfig.java:113
• FacturapiConfig.Builder still has baseUrl and objectMapper fields, but the corresponding builder setters were removed, so these fields can’t be configured by SDK consumers. This leaves dead/opaque configuration surface (and build() mutates these fields anyway), which hurts maintainability and makes it unclear whether overriding base URL / ObjectMapper is supported. Either remove these unused fields entirely, or reintroduce explicit builder methods and make build() respect user-provided values.
  src/main/java/io/facturapi/http/FacturapiConfig.java:69
• The SDK hard-codes the user agent as facturapi-java/0.1.x, which doesn’t match the artifact version (0.1.0-SNAPSHOT / README 0.1.0). Consider deriving this from the project version (or at least using a concrete version string) so server-side logs and support diagnostics can accurately identify client versions.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.