docs: align API specifications and correct SDK examples

.github/workflows/openapi.yml

@@ -0,0 +1,33 @@
+name: OpenAPI contract
+
+on:
+  pull_request:
+    paths:
+      - website/openapi_v2*.yaml
+      - website/scripts/check-openapi.mjs
+      - website/test/openapi-types.fixture.txt
+      - website/package.json
+      - website/pnpm-lock.yaml
+      - website/pnpm-workspace.yaml
+      - .github/workflows/openapi.yml
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  contract:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 11.5.1
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24.x
+          cache: pnpm
+          cache-dependency-path: website/pnpm-lock.yaml
+      - run: pnpm install --frozen-lockfile
+        working-directory: website
+      - run: pnpm test:openapi
+        working-directory: website

AGENTS.md

@@ -0,0 +1,28 @@
+# AGENTS.md
+
+## Public documentation and confidentiality
+
+- This is a public repository. Publish only the intended public API contract and
+  information authorized for public documentation.
+- Private sources may be consulted to verify API behavior. Never publish their
+  source code, internal file paths, commit hashes, implementation details,
+  private data, or internal plans in files, commit messages, pull requests,
+  review comments, issues, or CI output.
+- Keep evidence from private sources in private files or repositories. Explain
+  public corrections in terms of observable API behavior without citing private
+  implementation sources.
+- Keep PR titles and descriptions focused on the documentation change. Omit
+  unrelated internal plans and conversational context.
+- Before committing or publishing, review the full diff, commit messages, and
+  accompanying descriptions for confidential information.
+- If confidential information was published, a later deletion commit is not
+  sufficient. Clean affected branch history, verify remote references, and
+  explicitly report any host-side references or cached copies that remain.
+
+## API contract changes
+
+- Verify changes to types, required fields, defaults, authentication, parameters,
+  and status codes against authoritative sources. Do not treat an SDK declaration
+  or a review comment alone as proof of API behavior.
+- Keep the Spanish and English OpenAPI contracts structurally aligned.
+- Run the relevant repository checks for specification changes.

website/docs/getting-started/install.mdx

@@ -77,12 +77,12 @@ Importa la librería antes de usarla.
 <Tabs groupId="codeExamples">
 <TabItem value="js" label="Node.js" default>
 
-CommonJS
 ```javascript
-import Facturapi from 'facturapi'
+const Facturapi = require('facturapi');
 ```
 
-ESM / Typescript
+ESM / TypeScript
+
 ```javascript
 import Facturapi from 'facturapi';
 ```

website/docs/guides/invoices/cancelaciones.mdx

@@ -188,10 +188,14 @@ import fs from 'node:fs';
 const facturapi = new Facturapi('sk_test_API_KEY');
 
 const xmlStream = await facturapi.invoices.downloadCancellationReceiptXml('58e93bd8e86eb318b019743d');
-xmlStream.pipe(fs.createWriteStream('acuse_cancelacion.xml'));
+if ('pipe' in xmlStream && typeof xmlStream.pipe === 'function') {
+  xmlStream.pipe(fs.createWriteStream('acuse_cancelacion.xml'));
+}
 
 const pdfStream = await facturapi.invoices.downloadCancellationReceiptPdf('58e93bd8e86eb318b019743d');
-pdfStream.pipe(fs.createWriteStream('acuse_cancelacion.pdf'));
+if ('pipe' in pdfStream && typeof pdfStream.pipe === 'function') {
+  pdfStream.pipe(fs.createWriteStream('acuse_cancelacion.pdf'));
+}
 ```
 
 </TabItem>

website/docs/quickstart.mdx

@@ -373,9 +373,13 @@ import fs from 'fs';
 const zipStream = await facturapi.invoices.downloadZip(invoice.id);
 // Guarda la descarga en un archivo
 const file = fs.createWriteStream('./factura.zip');
-zipStream.pipe(file);
+if ('pipe' in zipStream && typeof zipStream.pipe === 'function') {
+  zipStream.pipe(file);
+}
 // O envíalo como respuesta a tu cliente (en ExpressJS)
-zipStream.pipe(res);
+if ('pipe' in zipStream && typeof zipStream.pipe === 'function') {
+  zipStream.pipe(res);
+}
 ```
 
 </TabItem>

website/docusaurus.config.js

@@ -62,7 +62,7 @@ const darkCodeTheme = require("prism-react-renderer").themes.dracula;
             },
             options: {
               disableSearch: true,
-              requiredPropsFirst: true,
+              sortRequiredPropsFirst: true,
               noAutoAuth: true,
             },
           },

website/i18n/en/docusaurus-plugin-content-docs/current/getting-started/install.mdx

@@ -77,12 +77,12 @@ Import the library before using it in your code.
 <Tabs groupId="codeExamples">
 <TabItem value="js" label="Node.js" default>
 
-CommonJS
 ```javascript
-import Facturapi from 'facturapi'
+const Facturapi = require('facturapi');
 ```
 
-ESM / Typescript
+ESM / TypeScript
+
 ```javascript
 import Facturapi from 'facturapi';
 ```

website/i18n/en/docusaurus-plugin-content-docs/current/guides/invoices/cancelaciones.mdx

@@ -174,10 +174,14 @@ import fs from 'node:fs';
 const facturapi = new Facturapi('sk_test_API_KEY');
 
 const xmlStream = await facturapi.invoices.downloadCancellationReceiptXml('58e93bd8e86eb318b019743d');
-xmlStream.pipe(fs.createWriteStream('cancellation_receipt.xml'));
+if ('pipe' in xmlStream && typeof xmlStream.pipe === 'function') {
+  xmlStream.pipe(fs.createWriteStream('cancellation_receipt.xml'));
+}
 
 const pdfStream = await facturapi.invoices.downloadCancellationReceiptPdf('58e93bd8e86eb318b019743d');
-pdfStream.pipe(fs.createWriteStream('cancellation_receipt.pdf'));
+if ('pipe' in pdfStream && typeof pdfStream.pipe === 'function') {
+  pdfStream.pipe(fs.createWriteStream('cancellation_receipt.pdf'));
+}
 ```
 
 </TabItem>

website/i18n/en/docusaurus-plugin-content-docs/current/quickstart.mdx

@@ -332,9 +332,13 @@ import fs from 'fs';
 const zipStream = await facturapi.invoices.downloadZip(invoice.id);
 // Save the downloaded file to disk
 const file = fs.createWriteStream('./factura.zip');
-zipStream.pipe(file);
+if ('pipe' in zipStream && typeof zipStream.pipe === 'function') {
+  zipStream.pipe(file);
+}
 // Or send it as a response to your customer (ExpressJS syntax)
-zipStream.pipe(res);
+if ('pipe' in zipStream && typeof zipStream.pipe === 'function') {
+  zipStream.pipe(res);
+}
 ```
 
 </TabItem>