Repository navigation
Conversation
javorosas
added this pull request to stack #122
September 29, 2026 15:46
javorosas
changed the title
Contributor
There was a problem hiding this comment.
Copilot review overview
🔵 Needs a closer look
Invoice creation currently returns untyped fields and leaves response timestamps as strings.
Review effort: Balanced
Findings: None
What changed in this PR
This PR prepares the SDK for v6 by generating its public types and resource methods from a pinned OpenAPI contract. It builds on the response-date work in #120 and coordinates with the public contract corrections in facturapi-docs#303.
Changes:
- Generate typed methods, models, and response-date plans while retaining the existing transport and webhook validation.
- Add ESM and CommonJS packaging, compatibility checks, and SDK generation checks.
- Update consumer migration guidance and release notes.
| File | Description |
|---|---|
| vitest.web.config.mts | Configures web unit tests. |
| vitest.node.config.mts | Configures Node unit tests. |
| vite.config.ts | Removes the old build configuration. |
| vite.config.mts | Configures ESM and CommonJS bundles. |
| test/node/sdk-generation.node.test.ts | Tests date-plan discovery. |
| test/node/runtime-compat.node.test.ts | Extends runtime response tests. |
| test/compat/node18-compat.test.cjs | Checks CommonJS compatibility. |
| test/compat/esm-compat.test.mjs | Checks native ESM imports. |
| test/browser/runtime-smoke.browser.spec.ts | Updates the browser bundle path. |
| test-d/runtime-types.test-d.ts | Tests public type contracts. |
| test-d/package-exports.mts | Checks ESM declarations. |
| test-d/package-exports.cts | Checks CommonJS declarations. |
| src/wrapper.ts | Applies generated response-date plans. |
| src/types/webhook.ts | Uses generated webhook types. |
| src/types/runtime.ts | Defines portable binary types. |
| src/types/retention.ts | Exposes generated retention aliases. |
| src/types/receipt.ts | Exposes generated receipt aliases. |
| src/types/product.ts | Exposes the generated product alias. |
| src/types/organization.ts | Exposes generated organization aliases. |
| src/types/invoice.ts | Exposes generated invoice aliases. |
| src/types/index.ts | Exports generated models. |
| src/types/customer.ts | Exposes generated customer aliases. |
| src/types/complements.ts | Exposes generated complement aliases. |
| src/types/common.ts | Exposes generated common aliases. |
| src/tools/webhooks.ts | Generates webhook methods. |
| src/tools/tools.ts | Adds the API health method. |
| src/tools/comercioExteriorCatalogs.ts | Generates catalog search typing. |
| src/tools/catalogs.ts | Generates catalog search typing. |
| src/tools/cartaPorteCatalogs.ts | Generates Carta Porte catalog methods. |
| src/runtime/webhooks.ts | Preserves signature validation and hydrates events. |
| src/runtime/uploads.ts | Prepares binary uploads. |
| src/runtime/dates.ts | Applies date plans to responses. |
| src/resources/retentions.ts | Generates typed retention methods. |
| src/resources/receipts.ts | Generates typed receipt methods and overloads. |
| src/resources/products.ts | Generates typed product methods. |
| src/resources/customers.ts | Generates typed customer methods. |
| src/generated/models.ts | Exports generated model aliases. |
| src/generated/dates.ts | Stores generated date plans. |
| src/generated/contracts.ts | Defines operation request and response types. |
| src/enums.ts | Adds complement enum members. |
| scripts/sync-openapi.mjs | Syncs the pinned public contract. |
| scripts/sdk/models.json | Maps public model names. |
| scripts/sdk/enums.json | Maps semantic enum bindings. |
| scripts/sdk/date-plans.mjs | Compiles date plans from types. |
| scripts/generate-sdk.mjs | Generates SDK files from OpenAPI. |
| scripts/commonjs-types.mjs | Produces CommonJS declarations. |
| rolldown.config.mjs | Configures declaration bundling. |
| README.md | Updates usage and migration guidance. |
| package.json | Prepares v6 exports, scripts, and dependencies. |
| openapi/source.json | Pins the public contract revision. |
| eslint.config.mjs | Adds the updated lint configuration. |
| eslint.config.js | Removes the old lint configuration. |
| CHANGELOG.md | Documents consumer-facing v6 changes. |
| AGENTS.md | Documents contributor generation practices. |
| .prettierignore | Excludes generated artifacts from formatting. |
| .gitignore | Ignores test and browser reports. |
| .github/workflows/ci.yml | Adds generation and compatibility checks. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
raul-facturapi
approved these changes
Oct 21, 2026
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.
Generate SDK request and response types, public model aliases, resource methods, and response date plans from the published OpenAPI contract. Preserve the HTTP transport, existing resource aliases, binary downloads and uploads, and local webhook signature verification.
Invoice responses form a status-based union of InvoiceDraft, InvoicePending, InvoiceFailed and InvoiceStamped. Valid and canceled invoices expose the required UUID and fiscal stamp fields after narrowing by status. The creation input remains unchanged, and the existing InvoiceStatus enum is preserved. The fiscal stamp original string is required and non-null on stamped invoices; stamp metadata includes its version and optional legend, while the invoice UUID remains the sole fiscal identifier.
Prepare SDK 6.0.0 with ESM and CommonJS package exports and matching declarations. Declared response timestamps become Date values; calendar dates and opaque metadata remain unchanged. Customer updates distinguish omitted fields from explicit null, including the separate edit-link input variant. ZIP requests support provenance filters and package freshness timestamps without a public forced-refresh option.
The specification is pinned to FacturAPI/facturapi-docs#311, which incorporates the renderer compatibility fixes from docs #313 and the shared fiscal stamp contract. Generated bindings follow the named cancellation-status schema while preserving the existing SDK enum. Deploy and verify the API guarantee for historical stamped invoices, then merge docs #311 before releasing this PR. Generation reads that immutable public source; runtime builds use tracked generated files.
Modernize build and declaration generation, dependencies, linting, package export checks, and browser coverage. Migration guidance remains in README; consumer changes are summarized in the 6.0.0 changelog.
Release coordination
After this PR merges, npm publication of 6.0.0 runs only after successful CI for the exact main push commit, and only if the version is not already published. Review the release and migration guidance before merging. The Node installation documentation PR FacturAPI/facturapi-docs#304 should follow publication because its direct CommonJS constructor example requires SDK 6.
This PR supersedes #120. PR #119 has merged. Its payroll catalog methods are included, ZIP methods are retained, and the published 5.2.0 changelog entry is preserved.
Validation
Tooling refreshed: ESLint 10.12, Prettier 3.9.10, typescript-eslint 8.71.2, Vite 8.3.4, Vitest 5.0.4, jsdom 30.1.2, globals and Node types. TypeScript stays on 6; Playwright stays on 1.63 under the dependency release-age policy. All validation above passed after these updates.
Review fixes preserve existing cancellation and organization response fields, correct series listing to an array, keep published changelog entries byte-identical to main, and clarify migration guidance. Built-package compatibility covers FIEL upload, receipt customer assignment and API health. No format check is added to CI; pre-commit fixes remain local.