Repository navigation
feat: generate typed SDK from OpenAPI and prepare v6 - #121
Merged
Merged
Conversation
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.
SDK v5 leaves many request fields loosely typed and does not consistently convert declared response timestamps to Date values. SDK v6 derives resource methods, request/response types, public model aliases, editor documentation, and date conversion plans from the published OpenAPI contract. Existing HTTP transport, binary uploads/downloads, resource aliases, and local webhook signature verification remain in place.
Invoice responses distinguish InvoiceDraft, InvoicePending, InvoiceFailed, and InvoiceStamped. Narrowing status to valid or canceled exposes the required UUID, invoice date, and fiscal stamp fields, including a non-null complement_string. Stamp version is required and discriminates TFD 1.0 from 1.1; selecting version 1.1 also guarantees the certifier RFC. The optional legend remains optional. Stamp dates remain SAT strings; declared date-time responses become Date values, while calendar dates and opaque metadata retain their original representation. Customer updates preserve the distinction between omitted values and explicit null, and receipt invoicing distinguishes invoice responses from dry-run summaries.
The public specification is pinned to the immutable contract commit from docs #318. The versioned stamp requirements come directly from that contract, with no generator-specific type patch. Generation remains reproducible for 120 operations and 269 schemas. Builds and runtime tests use tracked generated files. The Spanish README explains the stamp-version narrowing; CHANGELOG 6.0.0 summarizes consumer changes while preserving published entries.
The package supports Node.js 18+ and browsers, with ESM/CommonJS exports and matching TypeScript declarations. CommonJS supports the direct require constructor and retains .default compatibility. Tooling and build checks are updated; pre-commit formatting uses semicolons. No format gate is added to CI.
Merge docs #318 before releasing. Release remains conditional on verifying that the deployed API fulfills the documented stamp guarantees for stamped invoices. The SDK keeps those required types while that verification is pending. Merging triggers 6.0.0 publication only after CI succeeds for the exact main push commit, provided that version is not already published. The installation guide update should follow npm publication because its direct CommonJS constructor example requires v6. This supersedes #120; the merged #119 is incorporated.
Validation against the current pin: generation reproducibility, lint, build, TypeScript contracts, 53 Node tests, 10 web tests, five native package compatibility checks, and three Chromium smoke tests pass. An npm tarball was extracted into an isolated consumer directory; both ESM and CommonJS imports and their TypeScript declaration checks pass. The tarball contains only package metadata, license, README, changelog, and built runtime/declaration artifacts. CI separately checks compatibility on Node 18. No new test cases were added for this refresh.