Skip to content

CLAUDE.md

Latest commit

 

History

History
73 lines (52 loc) · 3.84 KB

CLAUDE.md

File metadata and controls

73 lines (52 loc) · 3.84 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Official NFE.io SDK for Node.js -- TypeScript native client for Brazilian electronic fiscal document APIs (NFS-e, NF-e, CT-e, CF-e). Version 3.x is a complete rewrite from the legacy v2 JavaScript/callback codebase (v2 lives in git history and is published as nfe-io@2.x on npm).

Build & Development Commands

npm run validate:spec    # Validate OpenAPI YAML specs
npm run generate         # Generate TypeScript types from OpenAPI specs into src/generated/
npm run build            # Full pipeline: validate:spec -> generate -> clean -> typecheck -> tsdown
npm run typecheck        # TypeScript strict check (tsc --noEmit)
npm run lint             # ESLint with auto-fix
npm run format           # Prettier formatting

Test Commands

npm test                 # Run all tests (vitest, watch mode)
npm test -- --run        # Run all tests once (no watch)
npm run test:unit        # Unit tests only (tests/unit/)
npm run test:integration # Integration tests only (tests/integration/)
npm run test:coverage    # Tests with v8 coverage report
npm test -- tests/unit/specific-file.test.ts  # Run a single test file

Coverage thresholds: 80% for branches, functions, lines, and statements. Test setup is in tests/setup.ts with mock data generators and test constants.

Architecture

Source Structure

  • src/index.ts -- Barrel export for all public API (NfeClient, types, errors)
  • src/core/client.ts -- Main NfeClient class with lazy-initialized resource getters and polling utilities
  • src/core/types.ts -- All TypeScript type definitions (config, resources, HTTP)
  • src/core/http/client.ts -- Fetch-based HTTP client with retry, timeout, rate-limit handling
  • src/core/errors/ -- Error hierarchy: NfeError base, then AuthenticationError, ValidationError, NotFoundError, RateLimitError, TimeoutError, ConnectionError, etc.
  • src/core/resources/ -- 17 resource implementations (service-invoices, companies, webhooks, etc.)
  • src/generated/ -- AUTO-GENERATED from OpenAPI specs. NEVER edit manually.

OpenAPI Pipeline

Specs live in openapi/spec/*.yaml. The generation script (scripts/generate-types.ts) produces typed interfaces in src/generated/. The build pipeline always validates and regenerates before compiling.

Key Patterns

  • Company-scoped operations: Most resource methods take company_id as first parameter
  • Async invoice processing: serviceInvoices.create() may return 202 + Location header; use polling utilities (pollUntilComplete, pollWithExponentialBackoff) for completion
  • Discriminated union returns: Create operations return typed results distinguishing immediate (201) vs async (202) responses
  • Lazy resource initialization: Resources on NfeClient are instantiated on first property access
  • Multiple API endpoints: Separate HTTP clients for different service APIs (main, CT-e, legal entity, natural person, etc.)

Module Output

Dual format via tsdown (Rolldown): ESM (dist/index.js) + CommonJS (dist/index.cjs) + type declarations (dist/index.d.ts). Target: Node.js 22+.

Code Style

  • TypeScript strict mode with noUncheckedIndexedAccess, exactOptionalPropertyTypes
  • Prettier: single quotes, trailing commas (ES5), 100 char width, semicolons
  • ESLint: no any types (warning), unused vars allowed with _ prefix
  • No runtime dependencies -- everything uses Node.js built-ins (Fetch, AbortController, Buffer)

Important Rules

  • Never edit files in src/generated/ -- they are overwritten by the generation pipeline
  • Run npm run generate after modifying any OpenAPI spec in openapi/spec/
  • Typecheck and tests must pass before commits (npm run typecheck && npm test -- --run)
  • The CHANGELOG is written in Portuguese