feat: generate typed SDK from OpenAPI and prepare v6

.gitattributes

@@ -0,0 +1,24 @@
+# Keep generated artifacts tracked, but collapse their diffs on GitHub.
+src/generated/contracts.ts linguist-generated=true
+src/generated/dates.ts linguist-generated=true
+src/generated/input.ts linguist-generated=true
+src/generated/models.ts linguist-generated=true
+src/generated/output.ts linguist-generated=true
+src/resources/customers.ts linguist-generated=true
+src/resources/invoices.ts linguist-generated=true
+src/resources/organizations.ts linguist-generated=true
+src/resources/products.ts linguist-generated=true
+src/resources/receipts.ts linguist-generated=true
+src/resources/retentions.ts linguist-generated=true
+src/tools/cartaPorteCatalogs.ts linguist-generated=true
+src/tools/catalogs.ts linguist-generated=true
+src/tools/nominaCatalogs.ts linguist-generated=true
+src/tools/comercioExteriorCatalogs.ts linguist-generated=true
+src/tools/tools.ts linguist-generated=true
+src/tools/webhooks.ts linguist-generated=true
+src/types/common.ts linguist-generated=true
+src/types/complements.ts linguist-generated=true
+src/types/customer.ts linguist-generated=true
+src/types/invoice.ts linguist-generated=true
+src/types/organization.ts linguist-generated=true
+src/types/receipt.ts linguist-generated=true

.github/workflows/ci.yml

@@ -8,30 +8,6 @@ on:
   workflow_dispatch:
 
 jobs:
-  quality:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v7
-
-      - name: Setup pnpm
-        uses: pnpm/action-setup@v6
-
-      - name: Setup Node
-        uses: actions/setup-node@v6
-        with:
-          node-version: 24
-          cache: pnpm
-
-      - name: Install dependencies
-        run: pnpm install --frozen-lockfile
-
-      - name: Check formatting
-        run: pnpm run format:check
-
-      - name: Run linter
-        run: pnpm run lint
-
   build-dist:
     runs-on: ubuntu-latest
     steps:
@@ -53,6 +29,9 @@ jobs:
       - name: Build package
         run: pnpm run build
 
+      - name: Verify generated SDK
+        run: pnpm run generate:sdk:check
+
       - name: Upload dist artifact
         uses: actions/upload-artifact@v7
         with:
@@ -80,7 +59,7 @@ jobs:
           path: dist
 
       - name: Run Node 18 runtime compatibility smoke
-        run: node --test test/compat/node18-compat.test.cjs
+        run: node --test test/compat/*.test.cjs test/compat/*.test.mjs
 
   node-runtime:
     runs-on: ubuntu-latest
@@ -149,6 +128,9 @@ jobs:
       - name: Run type contract tests
         run: pnpm run test:types
 
+      - name: Lint
+        run: pnpm run lint
+
   browser-smoke:
     runs-on: ubuntu-latest
     steps:

.github/workflows/deploy.yml

@@ -1,21 +1,31 @@
 name: Deploy to npm
 
 on:
-  push:
-    branches:
-      - main
+  workflow_run:
+    workflows: [CI]
+    types: [completed]
+    branches: [main]
 
 permissions:
   id-token: write # Required for OIDC authentication
   contents: read
 
 jobs:
   deploy:
+    if: >-
+      github.event.workflow_run.conclusion == 'success' &&
+      github.event.workflow_run.event == 'push' &&
+      github.event.workflow_run.head_branch == 'main'
+    env:
+      RELEASE_SHA: ${{ github.event.workflow_run.head_sha }}
     runs-on: ubuntu-latest
 
     steps:
       - name: Checkout repository
         uses: actions/checkout@v7
+        with:
+          ref: ${{ github.event.workflow_run.head_sha }}
+          persist-credentials: false
 
       - name: Setup pnpm
         uses: pnpm/action-setup@v6
@@ -101,7 +111,7 @@ jobs:
                 fields: [
                   { type: 'mrkdwn', text: `*Package:* \`${packageName}@${version}\`` },
                   { type: 'mrkdwn', text: `*Branch:* \`${process.env.GITHUB_REF_NAME}\`` },
-                  { type: 'mrkdwn', text: `*Commit:* \`${process.env.GITHUB_SHA}\`` },
+                  { type: 'mrkdwn', text: `*Commit:* \`${process.env.RELEASE_SHA}\`` },
                   { type: 'mrkdwn', text: `*Actor:* \`${process.env.GITHUB_ACTOR}\`` },
                 ],
               },
@@ -113,7 +123,7 @@ jobs:
                     '*Useful links*',
                     `• npm: <https://www.npmjs.com/package/${packageName}/v/${version}|View package>`,
                     `• Workflow run: <${process.env.GITHUB_SERVER_URL}/${process.env.GITHUB_REPOSITORY}/actions/runs/${process.env.GITHUB_RUN_ID}|Open run>`,
-                    `• Changelog: <${process.env.GITHUB_SERVER_URL}/${process.env.GITHUB_REPOSITORY}/blob/${process.env.GITHUB_SHA}/CHANGELOG.md|Read changes>`,
+                    `• Changelog: <${process.env.GITHUB_SERVER_URL}/${process.env.GITHUB_REPOSITORY}/blob/${process.env.RELEASE_SHA}/CHANGELOG.md|Read changes>`,
                   ].join('\n'),
                 },
               },
@@ -156,7 +166,7 @@ jobs:
                   text: [
                     `*Node SDK ${packageJson.version} publish failed*`,
                     `• Workflow run: <${process.env.GITHUB_SERVER_URL}/${process.env.GITHUB_REPOSITORY}/actions/runs/${process.env.GITHUB_RUN_ID}|Open run>`,
-                    `• Commit: \`${process.env.GITHUB_SHA}\``,
+                    `• Commit: \`${process.env.RELEASE_SHA}\``,
                   ].join('\n'),
                 },
               },

.gitignore

@@ -3,6 +3,8 @@
 test.js
 lib/
 dist/
+test-results/
+playwright-report/
 
 # Created by https://www.gitignore.io/api/node,macos,linux,windows,visualstudiocode
 

.husky/.gitignore

@@ -0,0 +1 @@
+_/

.husky/pre-commit

@@ -0,0 +1 @@
+pnpm exec lint-staged

.prettierignore

@@ -0,0 +1,7 @@
+dist/
+coverage/
+test-results/
+playwright-report/
+
+# Preserve published changelog entries as written.
+CHANGELOG.md

.vscode/settings.json

@@ -1,8 +1,4 @@
 {
-  "editor.defaultFormatter": "esbenp.prettier-vscode",
   "editor.formatOnSave": true,
-  "eslint.enable": true,
-  "editor.codeActionsOnSave": {
-    "source.fixAll.eslint": "explicit"
-  }
+  "eslint.enable": true
 }

AGENTS.md

@@ -0,0 +1,30 @@
+# Contributor instructions
+
+## Consumer documentation
+
+- Write `CHANGELOG.md` for developers who consume the SDK. Document observable behavior, public API and type changes, compatibility requirements, fixes, and any action required to upgrade.
+- Keep build tools, bundlers, test runners, lint/format configuration, CI setup, and development-only dependency updates out of the changelog. Explain those in pull request descriptions instead.
+- Summarize type changes by consumer capability or correction, not by individual fields or implementation steps. Put detailed upgrade cases in the README migration guide.
+- Keep changelog entries factual and concise. Use a friendly, task-oriented tone in the README; occasional emojis belong there, not in new changelog entries.
+- Preserve published changelog entries as written. Apply editorial changes only to new entries; correct historical entries only when a concrete factual error has been verified.
+- Keep migration guidance in the README. State which integrations need no code changes as explicitly as those that do. Verify historical behavior against released source before documenting a migration; do not infer a breaking change from a version number alone.
+
+## OpenAPI generation
+
+- Generate resource methods, request/response types, model aliases, and response date plans with `pnpm generate:sdk`. Do not edit files carrying a generation banner.
+- `openapi/source.json` pins a complete public FacturAPI/facturapi-docs commit SHA. `pnpm sync:openapi` resolves docs `main` to its current commit, downloads the spec from that exact commit, and records it only after parsing succeeds. An explicit public branch, tag or full SHA is supported for coordinated PRs. Run `pnpm generate:sdk` after syncing.
+- Generation always downloads the YAML from the recorded commit into memory; it never follows a moving branch or writes a spec snapshot. Builds and runtime tests use tracked generated files and need no spec download. Commit public documentation changes and sync their public ref before generating; do not record local filesystem paths or pin unpublished local changes.
+- Generate method summaries, argument descriptions and return documentation from OpenAPI. Keep SDK-specific binary upload/download and local webhook verification guidance in the generator; attach documentation to every public overload and use absolute documentation links.
+- `openapi-typescript` resolves the OpenAPI contract; the TypeScript compiler resolves the resulting types for date plans. Do not add a second JSON Schema interpreter or a handwritten date-path inventory.
+- `scripts/sdk/resources.json` maps public resource/method names to operation IDs. Use a string operation ID for normal endpoints; HTTP bindings and signatures are derived from the spec. Add overrides only for established argument names, optionality/nullability, fixed download formats, multipart/local-signature behavior, or response overloads. Do not repeat inferred path/body/query bindings. Every public HTTP operation must have a binding; adding an operation intentionally fails generation until its public method is chosen.
+- Use `bodySchema` for an explicit SDK convenience method that selects a specific input variant from the public spec while preserving the original HTTP operation. Keep `create()` available for dynamic or incomplete customer inputs; do not add runtime validation or rewrite the supplied body.
+- Use `querySchema` to bind a grouped query contract from the public spec when separate OpenAPI query parameters cannot express dependencies between them. Keep conditional values and required fields in that schema rather than repeating them in generator code. TypeScript cannot express arbitrary string exclusions (`not`); do not invent a narrower country catalog to work around that limitation.
+- Use `bodyByQueryFlag` only for a verified relationship between a query flag and an input schema that OpenAPI cannot express across parameters and request bodies. Keep both input schemas in the public spec; require a literal `true` to select the incomplete body and preserve the normal input for dynamic booleans.
+- Preserve the SDK convention that a declared request body is a required method argument unless the operation explicitly marks it optional (`required: false`) or a compatibility override says otherwise. Optional query objects accept null by default; explicit overrides preserve existing exceptions.
+- `scripts/sdk/models.json` preserves public model names. `scripts/sdk/enums.json` binds existing runtime enums to their semantic schema locations; never bind enums merely because their numeric/string values happen to match. Named enum drift must be corrected explicitly.
+- Preserve the real HTTP transport, binary behavior, and local cryptography. Test external HTTP boundaries with fixtures; do not replace these implementations with mocks.
+- Run `pnpm generate:sdk:check`, `pnpm test`, `pnpm lint`, and browser tests for generation changes. Cover input strings/Date values, nullable dates, complement discriminants, opaque metadata/XML, and additions to the contract.
+- This repository is public. Never copy private implementation sources, paths, identifiers, diagnostics, or planning context into generated files, tests, commits, PR descriptions, or review replies.
+- Keep the source commit metadata and generated sources tracked; do not commit a downloaded spec. Mark generated artifacts with `linguist-generated` in `.gitattributes` so reviews focus on the generator, bindings, runtime, and tests; keep handwritten configuration visible. Update the attributes when adding generated output files.
+- Describe current SDK capabilities in the README without release announcements; version references are appropriate when they explain verified compatibility or when a capability became available. Put release improvements in the changelog. The SDK supports Node.js and browsers; keep titles and summaries accurate for both.
+- Input schema names end in `Input`, including reusable input fragments. Keep intentionally shared shapes neutral. Correct inconsistent schema names in the public spec instead of adding direction guesses or per-schema patches to the generator; preserve published SDK aliases in `scripts/sdk/models.json`.

CHANGELOG.md

@@ -5,6 +5,31 @@ 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).
 
+## [6.0.0] Unreleased
+
+### Breaking
+
+- Response timestamps are consistently returned as `Date` objects. SAT stamp timestamps and calendar dates remain strings.
+- Request and response types now follow the API contract, with more precise CFDI and complement inputs. TypeScript integrations may need adjustments; see the [migration guide from v3, v4, and v5](README.md#actualizar-desde-v3-v4-o-v5).
+- Certificate deletion returns its update timestamp, global receipt invoicing may return `null`, and domain availability requires an explicit domain. See the concrete v5 migration cases in the README.
+- Series mutations return arrays, retention addendas use `string[]`, and uninvoiced receipts expose a nullable invoice reference. These type corrections match existing API responses.
+- Import from `facturapi`; direct imports into internal package files such as `facturapi/dist/...` are no longer supported.
+
+### Fixed
+
+- Correct request typing for partial product updates and native Node.js file uploads.
+- Webhook signature validation consistently returns parsed events with converted dates in Node.js and browsers.
+
+### Added
+
+- Autocompletion and editor documentation for request fields, method arguments, and responses across SDK operations.
+- More precise input types for CFDI variants, drafts, structured complements, and customer creation. Related fields are checked by TypeScript in supported cases, helping catch incomplete or incompatible inputs before sending a request.
+- Invoice responses distinguish draft, pending, failed, and stamped states; checking the status exposes the guaranteed UUID and stamp fields.
+- Receipt invoicing distinguishes invoice creation from `dry_run` summaries in its return types.
+- Methods to create national, foreign, and generic RFC customers with specific input types; assign receipt customers with `receipts.updateCustomer`; upload FIEL certificates; and check API health.
+- Filter invoice searches and monthly ZIP requests with `sat_imported`, inspect ZIP freshness with `is_current`, and access `generated_at` and `content_as_of` as `Date` objects.
+- CommonJS supports `const Facturapi = require('facturapi')` directly, while retaining `.default` compatibility. CommonJS and ESM include matching TypeScript definitions.
+
 ## [5.2.0] 2026-10-07
 
 ### Added