From 2af88cf6a09d8176604b94787bb30edc110b33a1 Mon Sep 17 00:00:00 2001
From: Andre Kutianski <andre@nfe.io>
Date: Fri, 12 Jun 2026 23:44:30 -0300
Subject: [PATCH] docs: corrigir README (Node 22, v4, skills.sh) e retorno de
 list na skill
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- README: Node 18 -> 22; rótulos v3 -> v4; badge + seção do skills.sh
  (npx skills add nfe/client-nodejs)
- SKILL.md: corrige o shape de retorno de list por recurso
  (serviceInvoices -> { serviceInvoices, totalResults, totalPages, page };
  companies/people/webhooks -> ListResponse { data, totalCount?, page };
  productInvoices -> { productInvoices, hasMore })
---
 README.md                      | 20 ++++++++++++++++----
 skills/nfeio-node-sdk/SKILL.md | 17 ++++++++++++++---
 2 files changed, 30 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index ae1e516..10bf5e5 100644
--- a/README.md
+++ b/README.md
@@ -1,19 +1,21 @@
-# NFE.io SDK para Node.js (v3)
+# NFE.io SDK para Node.js (v4)
 
 [![npm version](https://img.shields.io/npm/v/nfe-io.svg)](https://www.npmjs.com/package/nfe-io)
 [![Node.js Version](https://img.shields.io/node/v/nfe-io.svg)](https://nodejs.org)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue.svg)](https://www.typescriptlang.org/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![skills.sh](https://skills.sh/b/nfe/client-nodejs)](https://skills.sh/nfe/client-nodejs)
 
 **SDK Oficial NFE.io para Node.js 22+** - SDK TypeScript moderno para emissão de notas fiscais de serviço eletrônicas (NFS-e).
 
-> ✨ **Versão 3.0** - Reescrita completa com TypeScript, zero dependências em runtime e API moderna async/await.
+> ✨ **Versão 4** - TypeScript nativo, zero dependências em runtime e API moderna async/await.
 
 ## 📋 Índice
 
 - [Recursos](#-recursos)
 - [Instalação](#-instalação)
 - [Início Rápido](#-início-rápido)
+- [Skill para Agentes de IA](#-skill-para-agentes-de-ia)
 - [Documentação](#-documentação)
 - [Migração da v2](#-migração-da-v2)
 - [Exemplos](#-exemplos)
@@ -24,7 +26,7 @@
 ## ✨ Recursos
 
 - 🎯 **TypeScript Moderno** - Segurança de tipos completa com TypeScript 5.3+
-- 🚀 **Zero Dependências** - Usa API fetch nativa do Node.js (Node 18+)
+- 🚀 **Zero Dependências** - Usa API fetch nativa do Node.js (Node 22+)
 - ⚡ **Async/Await** - API limpa baseada em promises
 - 🔄 **Retry Automático** - Lógica de retry com exponential backoff integrada
 - 📦 **ESM & CommonJS** - Funciona com ambos os sistemas de módulos
@@ -35,7 +37,7 @@
 ## 📦 Instalação
 
 **Requisitos:**
-- Node.js >= 18.0.0
+- Node.js >= 22.0.0
 - TypeScript >= 5.0 (se usar TypeScript)
 
 ```bash
@@ -144,6 +146,16 @@ const nfe = new NfeClient({
 // Mesma API que ESM
 ```
 
+## 🤖 Skill para Agentes de IA
+
+Este repositório embarca uma skill que ensina agentes de código (Claude Code, Cursor, etc.) a usar o SDK corretamente. Instale com:
+
+```bash
+npx skills add nfe/client-nodejs
+```
+
+Descubra no diretório: [![skills.sh](https://skills.sh/b/nfe/client-nodejs)](https://skills.sh/nfe/client-nodejs)
+
 ## 📚 Documentação
 
 ### Recursos da API
diff --git a/skills/nfeio-node-sdk/SKILL.md b/skills/nfeio-node-sdk/SKILL.md
index a12901b..975fc7f 100644
--- a/skills/nfeio-node-sdk/SKILL.md
+++ b/skills/nfeio-node-sdk/SKILL.md
@@ -194,25 +194,36 @@ All error objects have: `message`, `type`, `code`/`status`/`statusCode`, `detail
 
 ## Core Pattern: Pagination
 
-The SDK uses **two different pagination styles**:
+The SDK uses **two different pagination styles**, and the response shape varies by resource:
 
 **Offset-based** (service invoices, companies, people, webhooks):
 ```typescript
+// Service invoices return { serviceInvoices, totalResults, totalPages, page }
 const page = await nfe.serviceInvoices.list(companyId, {
   pageIndex: 0,    // 0-based page number
   pageCount: 50,   // Items per page
 });
-// page.data: ServiceInvoiceData[]
-// page.totalCount: number
+page.serviceInvoices; // ServiceInvoiceData[]
+page.totalResults;    // number
+page.totalPages;      // number
+
+// Companies, people and webhooks return the generic ListResponse<T>
+const companies = await nfe.companies.list({ pageIndex: 0, pageCount: 50 });
+companies.data;       // Company[]
+companies.totalCount; // number | undefined
+companies.page;       // { pageIndex, pageCount }
 ```
 
 **Cursor-based** (product invoices, state taxes):
 ```typescript
+// Returns { productInvoices, hasMore }
 const page = await nfe.productInvoices.list(companyId, {
   environment: 'Production',   // REQUIRED for product invoices
   limit: 25,
   startingAfter: 'last-invoice-id',  // Cursor for next page
 });
+page.productInvoices; // NfeProductInvoiceWithoutEvents[]
+page.hasMore;         // boolean
 ```
 
 **Auto-pagination helpers** (companies only):