v4.0.386 complemento comercio exterior support and samples added

[mendozagit]

v4.0.386 complemento comercio exterior support and samples added

Summary by CodeRabbit

• New Features

  • Added manifest signing capability to the SDK
  • Added "Comercio Exterior" (Foreign Trade) complement support for CFDI invoices
  • Extended invoice models with international recipient identification fields
  • Added comprehensive example scripts for local taxes, payroll, foreign trade, and manifest signing

• Bug Fixes

  • Corrected API endpoint typos in example configurations

• Chores

  • Updated package version to 4.0.386
  • Standardized example configuration formatting and placeholders

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: c8f943da-a1cd-4efb-862f-4fdcf3788050

📥 Commits

Reviewing files that changed from the base of the PR and between 51d2e32 and 0e4296d.

📒 Files selected for processing (20)

• examples/ejemplo-datos-empleado-empleador.ts
• examples/ejemplo-timbres.ts
• examples/ejemplos-carta-porte-referencias.ts
• examples/ejemplos-carta-porte-valores.ts
• examples/ejemplos-comercio-exterior-referencias.ts
• examples/ejemplos-comercio-exterior-valores.ts
• examples/ejemplos-factura-impuestos-locales-referencias.ts
• examples/ejemplos-factura-impuestos-locales-valores.ts
• examples/ejemplos-factura-nomina-referencias.ts
• examples/ejemplos-factura-nomina-valores.ts
• examples/ejemplos-firma-manifiestos.ts
• package.json
• src/abstractions/fiscalapi-client.interface.ts
• src/abstractions/manifest-service.interface.ts
• src/index.ts
• src/models/invoice.ts
• src/models/manifest.ts
• src/models/person.ts
• src/services/fiscalapi-client.ts
• src/services/manifest-service.ts

---

📝 Walkthrough

Walkthrough

This PR introduces support for CFDI 4.0 Comercio Exterior (foreign trade) invoice complements and a new manifest signing service. It extends invoice and person models with international tax fields, implements the manifest service, integrates it into the FiscalAPI client, and adds comprehensive examples demonstrating both features across two operational modes (ByReferences and ByValues), plus standardizes configuration across existing examples.

Changes

Core Features: Comercio Exterior & Manifest Signing

Layer / File(s)	Summary
Comercio Exterior Complement Type System src/models/invoice.ts, src/models/person.ts	Adds ComercioExteriorComplement with nested types for issuer/receiver domicile, owners, destinatarios, and merchandise descriptions. Extends Complement, Invoice, and InvoiceRecipient with optional commerce-exterior fields. Extends Person with countryId and foreignTin for international tax identification.
Manifest Signing Models and Service Implementation src/models/manifest.ts, src/abstractions/manifest-service.interface.ts, src/services/manifest-service.ts	Introduces SignManifestRequest (base64 certificate/key + password) and SignManifestResponse (base64 file + metadata) DTOs. Defines IManifestService interface with sign contract. Implements ManifestService extending BaseFiscalapiService with null validation and POST request execution.
Client Integration: Manifest Service Wiring src/abstractions/fiscalapi-client.interface.ts, src/services/fiscalapi-client.ts	Adds manifests: IManifestService property to IFiscalapiClient. Integrates ManifestService into FiscalapiClient with imports and constructor initialization.
Public API Surface Exports src/index.ts	Re-exports IManifestService, all ComercioExterior* complement types, and manifest request/response models.

Examples and Documentation

Layer / File(s)	Summary
Example Configuration Standardization examples/ejemplo-*.ts, examples/ejemplos-factura-*.ts	Corrects API URLs (fisalapi.com → fiscalapi.com), standardizes placeholder casing for apiKey/tenant to lowercase, and adds inline comments documenting each settings field across eight existing examples.
Comercio Exterior Examples (ByReferences & ByValues) examples/ejemplos-comercio-exterior-referencias.ts, examples/ejemplos-comercio-exterior-valores.ts	Two 1000+ LOC example scripts demonstrating nine CFDI 4.0 Comercio Exterior scenarios in ByReferences and ByValues modes: ingreso with Carta Porte 31, multi-currency ingreso, kit parte, foreign/national recipients, traslado with CP31, traslado con mercancía propia, traslado traslado, and non-equivalent measurement units. ByReferences uses paired UpdatePeople/PorReferencias functions; ByValues uses inline issuer/recipient/item data with embedded SAT test certificates.
Manifest Signing Example examples/ejemplos-firma-manifiestos.ts	Self-contained example showing how to sign a fiscal manifest: configures SDK settings, embeds test SAT certificate/key material, constructs SignManifestRequest, calls client.manifests.sign, and logs response via main() with error handling.
Package Version Bump package.json	Version updated from 4.0.384 to 4.0.386.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• FiscalAPI/fiscalapi-node#5: Modifies invoice complement typing in src/models/invoice.ts; this PR adds comercioExterior complement while the related PR changes lading to cartaPorte.

Poem

🐰 A rabbit hops through foreign lands,
With manifests signed by swift commands,
Comercio Exterior now takes flight,
Invoices blessed with global sight!
Types and services shine so bright,
Examples guide the SDK's might. ✨

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/comercio-exterior

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint skipped: no ESLint configuration detected in root package.json. To enable, add eslint to devDependencies.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}