How dojocodinglabs/hacienda-cr works
Hacienda CR is a TypeScript toolkit for Costa Rican electronic invoicing, exposed through an SDK, terminal CLI, and MCP server. The main workflow prepares and validates document data, calculates amounts, builds XML, signs and submits it to Hacienda, then checks its status. The README documents these capabilities across the packages; sampled code confirms key client, authentication, HTTP, XML-builder, and MCP registration relationships. Some CLI and SDK subsystems are represented by their exact enclosing directories because their implementation files were not sampled.
Main entry points: client.ts SDK client · documents Document builders · commands CLI commands · orchestrator.ts Submission workflow
Components 25
User interfaces
- SDK client
packages/sdk/src/client.ts - CLI commands
packages/cli/src/commands - Draft creation
packages/cli/src/commands/draft.ts - CLI submission
packages/cli/src/commands/submit.ts - MCP server
packages/mcp/src/server.ts - MCP tools
packages/mcp/src/tools - MCP resources
packages/mcp/src/resources
SDK workflow
- OAuth authentication
packages/sdk/src/auth/token-manager.ts - Clave generation
packages/sdk/src/clave - Document builders
packages/sdk/src/documents - Tax calculation
packages/sdk/src/tax - XML validation
packages/sdk/src/xml - Digital signing
packages/sdk/src/signing - Submission workflow
packages/sdk/src/api/orchestrator.ts - Hacienda API client
packages/sdk/src/api/http-client.ts
Shared domain
- Document schemas
shared/src/schemas - Reference catalogs
shared/src/constants - Exact monetary math
shared/src/monetary/decimal-text.ts
Operations
- Configuration and sequences
packages/sdk/src/config - Delivery tracking
packages/sdk/src/delivery - Business calendar
packages/sdk/src/calendar - Status and lookups
packages/sdk/src/api/comprobantes.ts - Cancellation controls
packages/sdk/src/api/cancellation.ts
Other components
- Application or operator
- Hacienda services
Connections 29
- Application or operator → SDK client: uses SDK
- Application or operator → CLI commands: runs commands
- Application or operator → MCP server: connects assistant
- CLI commands → Draft creation: routes commands
packages/cli/src/commands/index.ts - CLI commands → CLI submission: routes commands
packages/cli/src/commands/index.ts - MCP server → MCP tools: registers tools
packages/mcp/src/server.ts - MCP server → MCP resources: registers resources
packages/mcp/src/server.ts - SDK client → OAuth authentication: initializes
packages/sdk/src/client.ts - SDK client → Clave generation: builds and parses
packages/sdk/src/client.ts - Draft creation → Document builders: prepares drafts
- MCP tools → Document builders: generates XML
- Document builders → Document schemas: validates input
packages/sdk/src/documents/exact-fec-foreign-service-builder.ts - Document builders → Tax calculation: calculates amounts
packages/sdk/src/documents/exact-fec-foreign-service-builder.ts - Tax calculation → Exact monetary math: uses exact arithmetic
- Document builders → XML validation: builds XML
packages/sdk/src/documents/exact-fec-foreign-service-builder.ts - Document schemas → Reference catalogs: uses catalogs
- CLI submission → Digital signing: signs documents
- SDK client → Digital signing: signs documents
- SDK client → Submission workflow: submits documents
- Submission workflow → Hacienda API client: calls API client
packages/sdk/src/api/orchestrator.ts - Hacienda API client → OAuth authentication: gets access token
packages/sdk/src/api/http-client.ts - Hacienda API client → Hacienda services: sends requests
- Submission workflow → Delivery tracking: tracks delivery
packages/sdk/src/api/orchestrator.ts - SDK client → Status and lookups: checks status
- CLI commands → Status and lookups: queries status
- Status and lookups → Hacienda services: queries records
- SDK client → Configuration and sequences: manages configuration
- SDK client → Business calendar: uses business days
- Submission workflow → Cancellation controls: supports cancellation
packages/sdk/src/api/orchestrator.ts