# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).

## [4.18.0] 2026-06-06
### Added
- Expose structured API error metadata through `FacturapiError`, including `status`, `code`, `path`, `location`, `errors`, `logId`, and response `headers`.

## [4.17.0] 2026-04-27
### Added
- Add support for custom request headers through the `Facturapi` constructor options.
- Add `receipts.toInvoice` to create customer invoices from multiple receipt keys.
- Add `receipts.previewToInvoicePdf` to generate PDF previews for to-invoice payloads.

## [4.16.0] 2026-04-23
### Added
- Add new export catalogs for customs regimes, transport keys, SCT permits, COFEPRIS sectors, pharmaceutical forms, special transport conditions, customs documents, transport types, transport figures, ISTMO registry, loading keys, maritime configurations, rail traffic, containers, rail cars, rail service types, transfer reasons, incoterms, and customs units.
- Expose the new enums on the `Facturapi` class as static getters for namespace-style access.

## [4.15.0] 2026-04-13
### Added
- Add `organizations.updateDefaultSeries` to set an organization default series by type.

### Fixed
- Return blob if content-type is octet-stream. This is the coverage for zip files 

## [4.14.2] 2026-03-31
### Fixed
- Add `TaxFactor.EXENTO` (`"Exento"`) to align SDK enums with the API/OpenAPI allowed tax factor values.

## [4.14.1] 2026-03-31
### Fixed
- Fix `organizations.checkDomainIsAvailable` to call `GET /organizations/domain-check` with query params (instead of an unsupported `PUT` payload flow).
- Align method input naming to query semantics for clearer usage (`query`).

## [4.14.0] 2026-03-04
### Added
- Add `facturapi.comercioExteriorCatalogs.searchTariffFractions` method for Fracción Arancelaria SAT catalog
- Add organization team/access management methods under `organizations`:
  `listTeamAccess`, `retrieveTeamAccess`, `removeTeamAccess`,
  `listSentTeamInvites`, `inviteUserToTeam`, `cancelTeamInvite`,
  `listReceivedTeamInvites`, `respondTeamInvite`,
  `listTeamRoles`, `listTeamRoleTemplates`, `listTeamRoleOperations`,
  `retrieveTeamRole`, `createTeamRole`, `updateTeamRole`, and `deleteTeamRole`.
- Add typed responses and inputs for organization access, invites, and roles.
- Add automated test suites for Node runtime (`vitest`), web-simulated runtime (`vitest` + `jsdom`), and browser smoke tests (`playwright`).
- Add TypeScript contract tests with `tsd` for public SDK types.
- Add CI workflow to run runtime tests, type tests, and browser smoke tests in GitHub Actions.
- Include `rfc_provider_cert` in stamp-related invoice typings and responses (thanks to @tetexxr).

### Changed
- Use `PUT` for role reassignment/update methods:
  `organizations.updateTeamAccessRole` and `organizations.updateTeamRole`.
- Use `Authorization: Bearer <apiKey>` by default in SDK requests (API supports this scheme).
- Improve cross-runtime compatibility through feature-detection based runtime handling and binary type normalization.
- Restrict npm published contents to runtime artifacts/docs (`dist`, `README`, `CHANGELOG`, `LICENSE`) using a package `files` whitelist.
- Pin `npm` to `10.9.2` in CI/deploy workflows for deterministic lockfile validation across Node versions.

### Fixed
- Improve non-OK HTTP error handling fallback when JSON error bodies are malformed or missing, returning clearer text/status errors.
- Handle `ReadableStream` read failures during binary download conversion to Node streams to avoid unhandled rejections.
- Strengthen WebCrypto webhook signature validation by using `subtle.verify` and explicit hex signature validation.
- Improve debugging for invalid upload inputs with clearer unsupported file type errors.

## [4.13.1] 2026-02-11

### Fixed

- Fix `organizations.uploadLogo` and `organizations.uploadCertificate` in Node.js 18 by avoiding `File` constructor usage during upload preparation.

### Changed

- Update declared Node.js engine requirement to `>=18.0.0` to match runtime dependencies.

## [4.13.0] 2026-02-06

### Added

- Add `CancellationStatus.VERIFYING` (`"verifying"`) to support SAT cancellation requests in verification.

## [4.12.0] 2026-01-21

### Changed

- Method of `retentions.cancel` now accept motive and substitution as in invoices cancellation method.

## [4.11.0] 2025-12-10

### Added

- Add new catalogs for cartaporte 
- `searchAirTransportCodes`, `searchTransportConfigs`,`searchRightsOfPassage`,`searchCustomsDocuments`,`searchPackagingTypes`,`searchTrailerTypes`, `searchHazardousMaterials`, `searchNavalAuthorizations`, `searchPortStations`, `searchMarineContainers`

## [4.10.0] 2025-09-04

### Added

- Add `invoices.previewPdf` method to generate a preview PDF of an invoice before stamping it.

## [4.9.1] 2025-07-21

### Fixed

- Deprecate `Organization.plan` property.

### Added

- Add `add_ons` property to the Organization type.
- Add missing attributes to `Organization.customization.pdf_extra`.

## [4.9.0] 2025-06-16

### Added

- Add `organizations.updateSelfInvoiceSettings` method to update self-invoice settings for the organization.

## [4.8.3] 2025-05-19

### Fixed

- Webhook validation. Now the signature is validated locally in Node and web environments (but not in React Native, where the API is still used).
- Type fixes for signature validation.

## [4.8.2] 2025-04-23

### Fixed

- Fix `organizations.uploadLogo` and `organizations.uploadCertificate` methods to accept `Buffer` or `ReadableStream` as input in Node.js.

## [4.8.1] 2025-04-10

### Fixed

- Fix route for `customers.sendEditLinkByEmail` method.

## [4.8.0] 2025-04-10

### Added

- Webhook events: `invoice.created_from_dashboard` and `customer.edit_link_completed`

## [4.7.0] 2025-04-04

### Added

- Add `customers.sendEditLinkByEmail` method to send an edit link to a customer via email.

## [4.6.0] 2025-02-25

### Added

- Allow creating edit links for customers, passing query params to create and edit customer methods.
- Edit link properties for customers.

## [4.5.0] 2025-01-07

### Added

- New fields for the Invoice object: `received_payment_ids` and `target_invoice_ids`,
  used to track payments and PPD invoices.

## [4.4.4] 2024-12-18

### Fixed

- Added try/catch to conditional import and define "stream" as external.

## [4.4.3] 2024-12-13

### Fixed

- Fix conditional import on web environments.

## [4.4.2] 2024-11-28

### Fixed

- Fix bug in Node.js environment in which the library was not returning the right kind of stream on download methods.

## [4.4.1] 2024-11-12

### Fixed

- Fix bug in which body params were not being sent in the request.

## [4.4.0] 2024-11-08

### Added

- Compatibility with browser environments and React Native. Now you can use Facturapi in the browser or in React Native, as long as you have a Fetch API compatible environment.
- Types for webhooks responses.
- Add `organizations.me` method to get the organization information.

### Fixed

- Name of validateSignature parameter "signature".

## [4.3.0] 2024-11-04

### Added

- Add types for all method responses. Method parameters are still not typed.

## [4.2.0] 2024-10-10

### Added

- List Live Api Keys: `listLiveApiKeys` for organizations
- Delete Live Api Keys: `deleteLiveApiKey` for organizations
- Validate webhooks responses: `validateSignature` for webhooks

## [4.1.2] 2024-07-15

### Added

- Fix optional `params` for invoice

## [4.1.1] 2024-06-15

### Fixed

- Fix `organization.createSeriesGroup` and `organization.updateSeriesGroup`. Thanks to @pastine

## [4.1.0] 2024-06-13

### Added

- Methods for CRUD of series
- Create method for series: `organization.createSeriesGroup`
- Read method for your organization series: `organization.listSeriesGroup`
- Update method for an specific series: `organization.updateSeriesGroup`
- Delete method for an specific series: `organization.deleteSeriesGroup`

## [4.0.0] 2024-05-23

### Breaking

- Remove deprecated method `products.keys` in favor of `catalogs.searchProducts`.
- Remove deprecated method `products.units` in favor of `catalogs.searchUnits`.
- Corrected the name of the method `invoices.editDraft` to `invoices.updateDraft`.
- The rest of the changes are internal and should not affect the public API.

### Added

- We rewrote the the library in TypeScript and now it's partially typed. Most request parameters and responses are not typed yet, but we plan to add more types in future releases.
- We export all type definitions, so you can use them in your TypeScript projects.
- New method to copy invoices to a new draft: `invoices.copyToDraft`.

## [3.6.0] 2024-05-23

### Added

- New method to delete certificates from the organization: `organizations.deleteCertificate`.
- New query param `async` in create invoice method:.
- New methods for draft invoices: `invoices.editDraft`, `invoices.stampDraft`.
- New method to update invoice status with the latest value from the SAT: `invoices.updateStatus`.

## [3.5.0] 2023-12-31

### Added

- Webhooks API

## [3.4.0] 2023-10-19

### Added

- Add `invoices.downloadCancellationReceiptPdf`.

## [3.3.0] 2022-12-14

### Added

- Add `invoices.downloadCancellationReceiptXml`, `receipts.sendByEmail` and `receipts.downloadPdf`.

## [3.2.0] 2022-01-17

Note: Although this update includes a breaking change, only the minor version will be bumped, since we haven't officially announced the new API version yet.

### Breaking

- Remove `organizations.getApiKeys`.

### Added

- Add `organizations.getTestApiKey`, `organizations.renewTestApiKey` and `organizations.renewLiveApiKey`.

## [3.1.0] 2022-01-17

### Added

- Allow setting the API version in the client constructor.

## [3.0.0] 2022-01-16

### Breaking

- Change API version to point to /v2, in order to support CFDI 4.0

## [2.7.0] 2021-12-27

### Added

- Support sending params to `invoices.cancel` method.

## [2.6.1] 2021-09-05

### Fixed

- Stop logging request config

## [2.6.0] 2021-08-06

### Added

- New endpoint: `tools.validateTaxId`.

## [2.5.0] 2021-04-13

### Added

- Support for Retentions API

### Security

- Updated dependencies to address potential vulnerabilities.

## [2.4.0] 2020-12-24 🎄

### Added

- New method on receipts API: `createGlobalInvoice`

## [2.3.1] 2020-05-28

### Fixed

- `facturapi.organizations.uploadCertificate` only accepted `FileStream`s. Now it supports any kind of readable `Stream`, as well as `Buffer`.

## [2.3.0] 2020-05-28

### Added

- Support for receipts API
- Edit organization's receipts settings
- Check domain availability
- Select organization's domain

## [2.2.3] 2020-03-05

### Fixed

- Use correct endpoint for `catalogs.searchProducts`

## [2.2.2] 2019-11-29

### Added

- Catalogs API
  - Search product keys using `catalogs.searchProducts`.
  - Search unit keys using `catalogs.searchUnits`.

### Fixed

- Updated all dependencies to clear security warnings
- Previously swallowing messages from non-axios errors

### Deprecated

- `product.keys` and `product.units` are deprecated in favor of the new catalogs API, and will be removed on the next major release.

## [2.0.0] 2018-08-04

### Breaking changes

- Now you must create the Facturapi instance using the `new` keyword every time.

**Before:**

```javascript
// This was allowed
const facturapi = Facturapi('YOUR_API_KEY');
```

**Now:**

```javascript
// Now you must always use new
const facturapi = new Facturapi('YOUR_API_KEY');
```

## [1.2.0] 2018-08-04

### Fixed

- Reject with an Error, not with an object

## [1.1.0] 2018-05-06

### Added

- Support Organizations API

## [1.0.0] - 2018-05-01

### Added

- Search `product_key`s using `facturapi.products.keys('your search')`
- Search `unit_key`s using `facturapi.products.units('your search')`
- Constants for PaymentMethod, InvoiceType, InvoiceUse, InvoiceRelation

### Breaking changes

- Now contants should be accessed as static properties from the Facturapi class, instead of from the instance.

**Before:**

```javascript
const facturapi = new Facturapi('YOUR_API_KEY');
console.log(facturapi.TaxType.IVA); // > IVA
```

**Now:**

```javascript
console.log(Facturapi.TaxType.IVA); // > IVA
```

## [0.1.3] - 2017-06-20

### Fixed

- Protocol should be HTTPS

## [0.1.2] - 2017-06-20

### Added

- First release
- Wrapper methods for:
  - Customers
  - Products
  - Invoices
- Added README file