snoopy_afip 4.3.0 → 4.3.1

data/docs/glossary/glossary.md

@@ -0,0 +1,74 @@
+# Glosario — snoopy_afip
+> meta: artefacto · RFC-009 · generado arch-enrich · anclado a 7813cf2 · cobertura: términos de dominio AFIP materializados en `lib/`; parcial, acreta por PR
+
+Bounded context: facturación electrónica AFIP (Argentina). Sin capa de datos (`docs/data/` n/a) → binding a símbolo público estable (ISO 11179), no a tabla.
+
+## WSAA
+
+Web Service de Autenticación y Autorización de AFIP. Recibe un CMS firmado (cert + clave privada) y devuelve `token` + `sign` válidos 12h (la gema pide `to = from + 12h`). Es el prerrequisito para operar contra WSFE.
+
+**Binding:** `Snoopy::AuthenticationAdapter` (`authentication_adapter.rb`); operación `:login_cms`.
+
+## WSFE
+
+Web Service de Facturación Electrónica v1 de AFIP. Autoriza comprobantes y devuelve el CAE. Requiere las credenciales de WSAA en cada request (`Auth`).
+
+**Binding:** `Snoopy::AuthorizeAdapter` (`authorize_adapter.rb`); operaciones `:fecae_solicitar`, `:fe_comp_ultimo_autorizado`, `:fe_comp_consultar`.
+
+## CAE (Código de Autorización Electrónico)
+
+Código que AFIP otorga al aprobar un comprobante; sin CAE la factura no es válida. Viene con fecha de vencimiento (`cae_fch_vto`).
+
+**Binding:** `Bill#cae`, `Bill#due_date_cae`; seteados en `AuthorizeAdapter#parse_fecae_solicitar_response`.
+
+## CMS / TRA
+
+**TRA** (Ticket de Requerimiento de Acceso): XML `loginTicketRequest` con `uniqueId`, `generationTime`, `expirationTime` y `service=wsfe`. **CMS**: el TRA firmado en PKCS7 (cert + pkey), base64, que se manda a WSAA.
+
+**Binding:** `AuthenticationAdapter#build_tra` (TRA), `#build_cms` (CMS).
+
+## cbte_type (tipo de comprobante)
+
+Código AFIP del tipo de comprobante (Factura A/B/C, Nota de Crédito A/B/C). En la gema se **deriva** de la condición IVA del receptor (`receiver_iva_cond`), no se pasa directo.
+
+**Binding:** `Bill#cbte_type` → `Snoopy::BILL_TYPE[receiver_iva_cond]`; tabla completa en `Snoopy::CBTE_TYPE`.
+
+## alicivas (alícuotas de IVA)
+
+Discriminación de IVA por ítem del comprobante: array de hashes `{id, amount, taxeable_base}` donde `id` es el porcentaje de IVA (0.105, 0.21, 0.27…) mapeado al código AFIP. Monotributistas no las informan.
+
+**Binding:** `Bill#alicivas`, `Bill::TAX_ATTRIBUTES`; código AFIP en `Snoopy::ALIC_IVA`; armado en `AuthorizeAdapter#build_body_request` (clave `Iva`).
+
+## Condición IVA — emisor vs receptor
+
+Tres conceptos distintos conviven:
+- **`issuer_iva_cond`** (emisor): determina si se informan alícuotas (monotributo no). Valores en `Snoopy::IVA_COND`.
+- **`receiver_iva_cond`** (receptor): determina el `cbte_type` (clave de `Snoopy::BILL_TYPE`).
+- **`receiver_iva_condition`** (RG 5616, "verdadera condición IVA del receptor"): id que AFIP exige en el detalle (`CondicionIVAReceptorId`). Valores en `Snoopy::IVA_COND_RECEIVER`.
+
+**Binding:** `Bill#issuer_iva_cond`, `#receiver_iva_cond`, `#receiver_iva_condition` / `#receiver_iva_condition_id`.
+
+## Resultado (A / P / R)
+
+Veredicto de AFIP sobre el comprobante: `A` aprobado, `P` aprobado parcial, `R` rechazado.
+
+**Binding:** `Bill#result`, `#approved?`, `#partial_approved?`, `#rejected?`.
+
+## afip_errors / afip_events / afip_observations
+
+Tres canales que AFIP devuelve en la respuesta, parseados en hashes `code => msg` separados. **Errores**: motivos de rechazo. **Eventos**: avisos de AFIP (ej. cambios futuros). **Observaciones**: motivos por los que no se autorizó. No son excepciones Ruby — el flujo no explota (ver `docs/behavior/`).
+
+**Binding:** `AuthorizeAdapter#afip_errors/#afip_events/#afip_observations`.
+
+## 3. Inferencias
+
+| término | confidence | nota |
+|---|---|---|
+| `receiver_iva_condition` (RG 5616) | inferred | el comentario del código dice "la verdadera condición de iva del receptor"; confirmar nombre de negocio exacto |
+| Candidato canónico (RFC-019) | inferred | `CAE`, `WSFE`, `condición IVA` probablemente aparecen en otros repos de facturación del fleet → candidatos a glosario canónico; arch-enrich no lo crea, lo flaggea |
+
+## 4. Cobertura y fronteras
+
+- Términos materializados en `lib/` actual. Acreta por PR.
+- Sin `Binding:` a tabla (gema sin datos); binding a símbolo público.
+- Significado de negocio profundo (reglas AFIP) fuera de alcance: referencia al manual del desarrollador AFIP (ver `docs/consumed/afip.md`).

data/docs/interface/interface.md

@@ -0,0 +1,86 @@
+# Interfaz — snoopy_afip
+> meta: artefacto · RFC-004 · generado arch-structure · anclado a 7813cf2 · cobertura: superficie pública de `lib/snoopy_afip/`
+
+## 1. Resumen
+
+API Ruby pública de la gema. Módulo raíz `Snoopy` (configuración global + helpers) y cuatro clases de dominio: `AuthenticationAdapter` (WSAA), `AuthorizeAdapter` (WSFE), `Bill` (comprobante), `Client` (wrapper Savon). Constantes de dominio en `Snoopy::*` y jerarquía de errores en `Snoopy::Exception::*`.
+
+## 2. Símbolos públicos
+
+| símbolo | tipo | nota |
+|---|---|---|
+| `Snoopy` | module | raíz; `extend self`; config global vía `attr_accessor` |
+| `Snoopy.cuit` `=` | accessor | CUIT del emisor |
+| `Snoopy.sale_point` `=` | accessor | punto de venta |
+| `Snoopy.service_url` `=` | accessor | WSDL de WSFE |
+| `Snoopy.auth_url` `=` | accessor | WSDL de WSAA |
+| `Snoopy.pkey` `=` | accessor | path/contenido de clave privada |
+| `Snoopy.cert` `=` | accessor | path/contenido de certificado |
+| `Snoopy.default_document_type` `=` | accessor | default de `Bill#document_type` |
+| `Snoopy.default_concept` `=` | accessor | default de `Bill#concept` |
+| `Snoopy.default_currency` `=` | accessor | default de `Bill#currency` |
+| `Snoopy.own_iva_cond` `=` | accessor | condición IVA propia |
+| `Snoopy.verbose` `=` | accessor | flag de verbosidad (Savon) |
+| `Snoopy.open_timeout` `=` | accessor | timeout de apertura; default `30` |
+| `Snoopy.read_timeout` `=` | accessor | timeout de lectura; default `30` |
+| `Snoopy.auth_hash` | method | `{"Token"=>…, "Sign"=>…, "Cuit"=>…}` — ver §3 |
+| `Snoopy.bill_types` | method | array `[etiqueta, código]` de tipos habilitados |
+| `Snoopy::Client` | class | wrapper de `Savon.client` |
+| `Snoopy::Client#initialize(attrs)` | method | `attrs` → opciones Savon |
+| `Snoopy::Client#call(service, args={})` | method | invoca SOAP con `Timeout`; devuelve `.body`; traduce fallos a `ServerTimeout`/`ClientError` |
+| `Snoopy::Client#savon` `=` | accessor | cliente Savon subyacente |
+| `Snoopy::AuthenticationAdapter` | class | flujo WSAA |
+| `…#initialize(attrs={})` | method | `attrs[:pkey]`, `attrs[:cert]` |
+| `…#authenticate!` | method | invoca `:login_cms`; devuelve hash con `:token`, `:sign`, `:expiration_time` |
+| `…#build_tra` | method | arma el TRA (XML) para `wsfe` |
+| `…#build_cms` | method | firma el TRA en PKCS7 → CMS base64 |
+| `….generate_pkey(leng=8192)` | class method | genera clave privada RSA PEM |
+| `….generate_certificate_request_with_ruby(pkey, subj_o, subj_cn, subj_cuit)` | class method | CSR vía OpenSSL Ruby |
+| `….generate_certificate_request_with_bash(pkey, subj_o, subj_cn, subj_cuit)` | class method | CSR vía `openssl req` (shell) |
+| `Snoopy::AuthorizeAdapter` | class | flujo WSFE |
+| `…#initialize(attrs)` | method | `:bill, :cuit, :sign, :pkey, :cert, :token` |
+| `…#authorize!` | method | invoca `:fecae_solicitar`; setea CAE/result en `bill`; devuelve bool |
+| `…#set_bill_number!` | method | invoca `:fe_comp_ultimo_autorizado`; setea `bill.number` |
+| `…#invoice_informed?` | method | invoca `:fe_comp_consultar`; devuelve bool |
+| `…#auth` | method | `{"Token"=>…, "Sign"=>…, "Cuit"=>…}` de la instancia |
+| `…#errors` `=` | accessor | errores internos de parseo (hash de excepciones) |
+| `…#afip_errors` `=` | accessor | errores devueltos por AFIP (`code=>msg`) |
+| `…#afip_events` `=` | accessor | eventos devueltos por AFIP |
+| `…#afip_observations` `=` | accessor | observaciones devueltas por AFIP |
+| `…#request` `=` / `#response` `=` | accessor | payload enviado / respuesta cruda |
+| `Snoopy::Bill` | class | modela el comprobante |
+| `…#initialize(attrs={})` | method | ver §4 README para `attrs` |
+| `…#valid?` | method | corre validaciones; puebla `#errors` |
+| `…#errors` `=` | accessor | hash `attr => [mensajes]` |
+| `…#total` | method | neto + IVA, redondeado 2 |
+| `…#iva_sum` | method | suma de `amount` de `alicivas` |
+| `…#cbte_type` | method | código de comprobante según `receiver_iva_cond` |
+| `…#cbte_asoc_type` | method | código del comprobante asociado |
+| `…#receiver_iva_condition_id` | method | id de condición IVA del receptor (RG 5616) |
+| `…#exchange_rate` | method | `1` si `:peso`; resto sin implementar (ver §3) |
+| `…#approved?` / `#rejected?` / `#partial_approved?` | method | estado del resultado AFIP (`A`/`R`/`P`) |
+| `…#to_h` / `#to_hash` | method | volcado de instance vars |
+| `Snoopy::Bill::ATTRIBUTES` | const | lista de `attr_accessor` del comprobante |
+| `Snoopy::Bill::TAX_ATTRIBUTES` | const | `[:id, :amount, :taxeable_base]` |
+| `Snoopy::Bill::ATTRIBUTES_PRECENSE` | const | atributos requeridos en validación |
+| `Snoopy::CBTE_TYPE` `Snoopy::BILL_TYPE` `Snoopy::CONCEPTS` `Snoopy::DOCUMENTS` `Snoopy::CURRENCY` `Snoopy::ALIC_IVA` `Snoopy::IVA_COND` `Snoopy::IVA_COND_RECEIVER` | const | tablas de dominio (ver `docs/data/` n/a → enriquecer en glosario) |
+| `Snoopy::RESPONSABLE_INSCRIPTO` `…_MONOTRIBUTO` `CONSUMIDOR_FINAL` `IVA_SUJETO_EXENTO` `IVA_NO_ALCANZADO` | const | símbolos de condición IVA |
+| `Snoopy::SNOOPY_SSL_VERSION` | const | versión TLS (de `ENV['SNOOPY_SSL_VERSION']`, default `:TLSv1`) — ver `docs/config/` |
+| `Snoopy::Exception::*` | module/class | jerarquía de errores — ver `docs/errors/` |
+| `String#underscore` `Hash#symbolize_keys[!]` `Hash#deep_symbolize_keys` `Hash#underscore_keys[!]` `Float#round_with_precision` `Float#round_up_with_precision` | core_ext | **monkey-patches globales** sobre `String`/`Hash`/`Float` — contaminan el host (ver §4) |
+
+## 3. Inferencias
+
+| ítem | confidence | a verificar |
+|---|---|---|
+| `Bill#exchange_rate` solo resuelve `:peso` (`return 1`); el resto del método está comentado → devuelve `nil` para moneda extranjera | declared | confirmar si es intencional o feature incompleta |
+| `Snoopy.auth_hash` usa `Snoopy::TOKEN` / `Snoopy::SIGN` (constantes **no definidas** en el código leído) | declared | `auth_hash` levantaría `NameError`; `AuthorizeAdapter#auth` es la vía viva — confirmar si `auth_hash` es legacy muerto |
+| `core_ext` define métodos solo `unless method_defined?` (Hash/String) pero `Float` y `String#underscore` se redefinen siempre | declared | colisión potencial con ActiveSupport en hosts Rails |
+
+## 4. Cobertura y fronteras
+
+- **Significado de negocio** de constantes/atributos → fuera de alcance (va a `docs/glossary/`, arch-enrich).
+- **Errores** detallados → `docs/errors/` (RFC-020).
+- **Config runtime** (`ENV`, accessors) → `docs/config/` (RFC-012).
+- **core_ext globales**: la gema parchea `String`/`Hash`/`Float` del host — superficie pública de facto aunque no sea el API previsto; el impacto (colisión con ActiveSupport) es concern de comportamiento → arch-enrich.
+- `Snoopy::Exception::ServerTimeout < Timeout::Error` (no hereda de `Snoopy::Exception::Exception`) — detalle en `docs/errors/`.

data/docs/test/testing.md

@@ -0,0 +1,74 @@
+# Test — snoopy_afip
+> meta: artefacto · RFC-013 · generado arch-structure · enriquecido arch-enrich · anclado a 7813cf2 (suite reescrita en fix/specs-and-lock) · cobertura: inventario estructural; §e-§h 4/4
+
+## 1. Resumen
+
+Suite RSpec en `spec/`, **reescrita contra la API actual y verde** (`21 examples, 0 failures`). Corre bajo **Ruby 2.7.x** (runtime del consumidor `argentina_invoice_service`). En **Ruby 3.x la gema no carga**: el stack de savon 2.12 (httpi 2.x) depende de `kconv` (removido de stdlib en 3.x) y de `Rack::Utils::HeaderHash` (removido en rack 3) → correr en 3.x requiere el upgrade de savon (gated, ver #13/roadmap).
+
+## 2.a Suites, frameworks y niveles
+
+| framework | archivo | propósito | nivel |
+|---|---|---|---|
+| RSpec | `spec/snoopy_afip/bill_spec.rb` | `Bill`: cbte_type, iva_sum/total, exchange_rate, receiver_iva_condition_id, estado del resultado, `valid?` | unit |
+| RSpec | `spec/snoopy_afip/authorize_adapter_spec.rb` | `AuthorizeAdapter`: `auth`, y regresión de rescues de parseo (#10/#16) | unit |
+| RSpec | `spec/snoopy_afip/authentication_adapter_spec.rb` | `AuthenticationAdapter`: `build_tra`, credenciales de instancia | unit |
+| RSpec | `spec/snoopy_afip/exceptions_spec.rb` | jerarquía `Snoopy::Exception` + paraguas `Error` (regresión #14) | unit |
+| RSpec | `spec/spec_helper.rb` | bootstrap + config base de homologación | — |
+
+## 2.b Comando de corrida
+
+```bash
+bundle exec rspec    # bajo Ruby 2.7.x
+```
+
+No hay CI declarado (sin `.github/workflows/`, `.circleci/`, `bin/ci`, `config/ci.rb`). Corrida solo local. Dev-deps de test: `rspec ~> 3.13`, `activesupport` (gemspec); pin `rack ~> 2.2` (Gemfile, requerido por httpi 2.x).
+
+## 2.c Fixtures / Factories
+
+- **Sin fixtures en disco.** Los specs son unit puros: construyen `Bill`/adapters con placeholders inline; no requieren `spec/fixtures/pkey`/`cert.crt` ni llamadas reales a AFIP.
+- Sin FactoryBot, sin VCR. Las URLs de homologación se setean en `spec_helper.rb` pero ninguna prueba abre conexión (Savon es lazy salvo el build del cliente, que no conecta).
+- `Bill#valid?` necesita `blank?`/`present?` → `spec_helper` carga `active_support/core_ext/object/blank`.
+
+## 2.d Configuración de coverage
+
+Ninguna (sin `.simplecov` / `SimpleCov.start`). Sin umbral declarado.
+
+## 2.e Gaps de cobertura
+
+**Cubierto** (unit, sin red): lógica de `Bill` (cálculos, validaciones, mapeos de dominio), jerarquía de excepciones + paraguas, `build_tra`, y el **comportamiento de los rescues de parseo** (no explotan, registran String).
+
+**NO cubierto** (requiere mock de Savon / VCR / homologación real):
+- `authorize!` / `set_bill_number!` / `invoice_informed?` — el camino feliz contra WSFE (no se mockea la respuesta SOAP).
+- `authenticate!` / `build_cms` — firma CMS con cert/pkey reales.
+- `parse_*` con respuestas AFIP **válidas** (solo se testea el path de error).
+- `core_ext` (`round_with_precision`, `deep_symbolize_keys`, `underscore`).
+
+## 2.f Contract-assessment
+
+| contrato público | test? |
+|---|---|
+| operaciones (RFC-003) | n/a (gema sin superficie) |
+| dependencias consumidas WSAA/WSFE (RFC-018) | **parcial** — `build_tra` sí; las llamadas SOAP no se ejercitan (sin mock/VCR) |
+| errores públicos (RFC-020) | **sí** — jerarquía `Snoopy::Exception::*` + paraguas `Error` + comportamiento de los rescues |
+
+## 2.g Link a incidente
+
+- `exceptions_spec.rb` fija la jerarquía de `ServerTimeout` (regresión de **#14**).
+- `authorize_adapter_spec.rb` fija que los rescues de parseo no explotan y registran String (regresión de **#10/#16** — el diseño "No Explota" que nació de un incidente real con cambios de formato de AFIP).
+
+## 2.h PII en fixtures
+
+- Sin fixtures con PII (no hay fixtures en disco). `pkey`/`cert`/`cuit` en specs son placeholders inline (`/tmp/pkey`, `"20111111112"`), nunca material real.
+
+## 3. Inferencias
+
+| ítem | confidence | a verificar |
+|---|---|---|
+| La gema no carga en Ruby 3.x (kconv/httpi 2.x, Rack::Utils::HeaderHash/rack 3) | declared | desbloquea con el upgrade de savon a 2.15+ (httpi 4) — gated |
+| El lock está resuelto para Ruby 2.7 (nokogiri 1.15.7, rack 2.2) | declared | un dev en Ruby 3.x no podrá `bundle install` hasta el upgrade |
+
+## 4. Cobertura y fronteras
+
+- El contenido detallado de cada test queda en el código.
+- Falta cobertura de los caminos felices contra AFIP (necesita mock de Savon o VCR) — próximo incremento.
+- La corrida en Ruby 3.x está bloqueada por el stack de dependencias, no por los specs.

data/docs/topology/topology.md

@@ -0,0 +1,44 @@
+# Topología — snoopy_afip
+> meta: artefacto · RFC-006 · generado arch-structure · anclado a 7813cf2 · cobertura: deps de runtime + servicios externos AFIP
+
+## 1. Resumen
+
+Gema cliente SOAP. Una sola dependencia de runtime declarada en el `.gemspec` (`savon`), que arrastra el stack SOAP (httpi, nori, gyoku, akami, wasabi, nokogiri). Consume dos servicios SOAP externos de AFIP: WSAA (auth) y WSFE (facturación). No corre como proceso propio: se embebe en el host (típicamente una app Rails).
+
+## 2. Dependencias
+
+| nombre | versión | rol |
+|---|---|---|
+| `savon` | `~> 2.12.1` (gemspec) · `2.12.0` (lock) | cliente SOAP — única dep de runtime declarada |
+| `httpi` | `2.4.4` (lock, transitiva) | capa HTTP de savon |
+| `nori` | `2.6.0` (lock, transitiva) | XML→Hash (usado directo en `AuthenticationAdapter`) |
+| `nokogiri` | `1.10.9` (lock, transitiva) | parser XML; usado directo en `build_tra` (`Nokogiri::XML::Builder`) |
+| `gyoku` `akami` `wasabi` `builder` `rack` `socksify` `mini_portile2` | ver lock | transitivas de savon |
+| `OpenSSL` (stdlib) | — | firma CMS/PKCS7, generación de clave/CSR |
+| `Timeout` (stdlib) | — | corta llamadas SOAP (`Snoopy::Client#call`) |
+
+## 3. Grafo
+
+```mermaid
+flowchart LR
+  Host["App host (Rails)"] -->|require| Snoopy["snoopy_afip"]
+  Snoopy -->|Savon.client| Savon["savon (SOAP)"]
+  Savon -->|HTTP/SOAP| WSAA["AFIP WSAA<br>login_cms"]
+  Savon -->|HTTP/SOAP| WSFE["AFIP WSFE<br>fecae_solicitar / fe_comp_*"]
+  Snoopy -->|firma CMS| OpenSSL["OpenSSL (stdlib)"]
+  Snoopy -->|build_tra| Nokogiri["nokogiri"]
+  Snoopy -->|parse| Nori["nori"]
+```
+
+## 4. Modos de ejecución
+
+| modo | aplica | nota |
+|---|---|---|
+| librería embebida | sí | se usa dentro del proceso del host; sin daemon/worker propio |
+| web / worker / cron propios | no | la gema no define procesos |
+
+## 5. Cobertura y fronteras
+
+- **`Gemfile.lock` divergente** (ver `docs/test/` y nota global): el lock fija `snoopy_afip (4.0.1)` mientras `version.rb` dice `4.3.0`, y lista en `PATH specs` deps (`akami`, `nokogiri`, `nori`, `wasabi`) que el `.gemspec` **actual** no declara explícitamente (solo `savon`). El lock parece no regenerado tras cambios de gemspec/versión. Versiones de la tabla tomadas del lock como mejor evidencia disponible, marcadas.
+- Servicios AFIP externos (WSAA/WSFE): contrato consumido en `docs/consumed/` (RFC-018).
+- Topología upstream de AFIP (infra del organismo) fuera de alcance.

data/lib/snoopy_afip/authorize_adapter.rb

@@ -114,7 +114,7 @@ module Snoopy
         [obs].flatten.each { |ob| afip_observations[ob[:code]] = ob[:msg] }
       end
     rescue => e
-      errors << Snoopy::Exception::AuthorizeAdapter::ObservationParser.new(e.message, e.backtrace)
+      @errors[:observation_parser] = Snoopy::Exception::AuthorizeAdapter::ObservationParser.new(e.message, e.backtrace).message
     end
 
     def parse_events(fecae_events)
@@ -122,7 +122,7 @@ module Snoopy
         [events].flatten.each { |event| afip_events[event[:code]] = event[:msg] }
       end
     rescue => e
-      errors << Snoopy::Exception::AuthorizeAdapter::EventsParser.new(e.message, e.backtrace)
+      @errors[:events_parser] = Snoopy::Exception::AuthorizeAdapter::EventsParser.new(e.message, e.backtrace).message
     end
 
     def parse_errors(fecae_errors)
@@ -130,7 +130,7 @@ module Snoopy
         [errores].flatten.each { |error| afip_errors[error[:code]] = error[:msg] }
       end
     rescue => e
-      errors << Snoopy::Exception::AuthorizeAdapter::ErrorParser.new(e.message, e.backtrace)
+      @errors[:error_parser] = Snoopy::Exception::AuthorizeAdapter::ErrorParser.new(e.message, e.backtrace).message
     end
 
     def parse_fecae_solicitar_response
@@ -154,7 +154,7 @@ module Snoopy
         parse_errors(fecae_result[:errors])                       if fecae_result.has_key? :errors
         parse_events(fecae_result[:events])                       if fecae_result.has_key? :events
       rescue => e
-        @errors << Snoopy::Exception::AuthorizeAdapter::FecaeResponseParser.new(e.message, e.backtrace)
+        @errors[:fecae_response_parser] = Snoopy::Exception::AuthorizeAdapter::FecaeResponseParser.new(e.message, e.backtrace).message
       end
     end
 
@@ -179,7 +179,7 @@ module Snoopy
       self.parse_errors(fe_comp_consultar_result[:errors]) if fe_comp_consultar_result and fe_comp_consultar_result.has_key? :errors
       self.parse_events(fe_comp_consultar_result[:events]) if fe_comp_consultar_result and fe_comp_consultar_result.has_key? :events
     rescue => e
-      @errors << Snoopy::Exception::FecompConsultResponseParser.new(e.message, e.backtrace)
+      @errors[:fecomp_consult_response_parser] = Snoopy::Exception::AuthorizeAdapter::FecompConsultResponseParser.new(e.message, e.backtrace).message
     end
 
     def client_configuration

data/lib/snoopy_afip/exceptions.rb

@@ -1,7 +1,18 @@
+require "timeout" # ServerTimeout < Timeout::Error; en Ruby 3.4+ timeout es default gem no autocargado
+
 module Snoopy
   module Exception
 
+    # Paraguas de todos los errores que emite la gema. Se incluye en la base
+    # `Exception` (y por herencia en todas sus subclases) y en `ServerTimeout`,
+    # que debe seguir siendo un `Timeout::Error` por compatibilidad hacia atrás.
+    # Permite `rescue Snoopy::Exception::Error` para atrapar cualquier error de
+    # la gema, incluido el timeout, sin romper `rescue Timeout::Error`.
+    module Error; end
+
     class  Exception < ::StandardError
+      include Error
+
       attr_accessor :backtrace
 
       def initialize(msg, backtrace)
@@ -17,6 +28,7 @@ module Snoopy
     end
 
     class ServerTimeout < Timeout::Error
+      include Error
     end
 
     module AuthenticationAdapter

data/lib/snoopy_afip/version.rb

@@ -1,3 +1,3 @@
 module Snoopy
-  VERSION = "4.3.0"
+  VERSION = "4.3.1"
 end

data/lib/snoopy_afip.rb

@@ -23,10 +23,6 @@ module Snoopy
   self.open_timeout ||= 30
   self.read_timeout ||= 30
 
-  def auth_hash
-    {"Token" => Snoopy::TOKEN, "Sign"  => Snoopy::SIGN, "Cuit"  => Snoopy.cuit}
-  end
-
   def bill_types
     [
       ["Factura A", "01"],

data/skill/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: snoopy-afip
+description: >
+  Gema Ruby `snoopy_afip` — adaptador de Facturación Electrónica de AFIP
+  (Argentina). Resuelve los servicios SOAP WSAA (autenticación: token/sign a
+  partir de cert+pkey) y WSFE (autorización de comprobantes: devuelve CAE) vía
+  `savon`. Activá esta skill cuando trabajes con emisión de facturas/notas de
+  crédito electrónicas argentinas, autenticación contra AFIP, el módulo
+  `Snoopy`, o las clases `AuthenticationAdapter` / `AuthorizeAdapter` / `Bill`.
+triggers:
+  - "facturación electrónica AFIP"
+  - "emitir factura electrónica argentina"
+  - "autenticar contra WSAA"
+  - "autorizar comprobante WSFE"
+  - "obtener CAE de AFIP"
+  - "usar la gema snoopy_afip"
+  - "Snoopy::AuthorizeAdapter / Snoopy::Bill"
+---
+
+# snoopy_afip — skill de agente
+
+Contrato resumido de la gema. El detalle vive en `docs/<capa>/` (anclado a `4.3.0` / commit `7813cf2`); esta skill indexa y resume.
+
+## Qué es / cuándo usar
+
+Adaptador de la Facturación Electrónica de AFIP. Úsala para autenticar (WSAA) y autorizar comprobantes (WSFE) desde Ruby. Se configura en el host vía `Snoopy.<attr> = …` y se opera con tres clases. No corre como proceso propio: es librería embebida.
+
+## Contrato resumido (piso mínimo)
+
+**Flujo típico** (autenticar → numerar → autorizar):
+
+```ruby
+auth = Snoopy::AuthenticationAdapter.new(pkey: pkey, cert: cert)
+creds = auth.authenticate!                      # {token, sign, expiration_time} (12h)
+
+bill = Snoopy::Bill.new(cuit:, sale_point:, concept:, document_type:, document_num:,
+                        issuer_iva_cond:, receiver_iva_cond:, receiver_iva_condition:,
+                        total_net:, alicivas:)   # alicivas: [{id:, amount:, taxeable_base:}]
+adapter = Snoopy::AuthorizeAdapter.new(bill:, pkey:, cert:, cuit:,
+                                       token: creds[:token], sign: creds[:sign])
+adapter.set_bill_number!                         # último autorizado + 1
+adapter.authorize!                               # setea bill.cae / bill.result
+```
+
+**Símbolos clave:** `Snoopy` (config global), `Snoopy::AuthenticationAdapter` (WSAA), `Snoopy::AuthorizeAdapter` (WSFE), `Snoopy::Bill` (comprobante), `Snoopy::Client` (wrapper Savon). Tablas de dominio: `Snoopy::BILL_TYPE`, `ALIC_IVA`, `IVA_COND_RECEIVER`, `DOCUMENTS`, `CURRENCY`.
+
+**Gotchas (load-bearing):**
+- `receiver_iva_cond` (key de `BILL_TYPE`) determina el `cbte_type` — distinto de `issuer_iva_cond` y de `receiver_iva_condition` (RG 5616). Ver glosario.
+- **Tras timeout en `authorize!` no reintentar a ciegas**: el comprobante pudo emitirse en AFIP — verificar con `invoice_informed?` (`docs/consumed/afip.md §c`).
+- AFIP exige TLS ≥1.2; el default `SNOOPY_SSL_VERSION=:TLSv1` quedó desactualizado (`docs/config/configuracion.md §f`).
+- `pkey`/`cert`/`cuit` son secretos: setear en el host, nunca commitear.
+- La gema **parchea globalmente** `String`/`Hash`/`Float` (core_ext) — posible colisión con ActiveSupport.
+
+## Índice de artefactos
+
+| capa | path | nota |
+|---|---|---|
+| interfaz | [`docs/interface/interface.md`](../docs/interface/interface.md) | API Ruby pública |
+| comportamiento | [`docs/behavior/behavior.md`](../docs/behavior/behavior.md) | secuencias WSAA/WSFE |
+| glosario | [`docs/glossary/glossary.md`](../docs/glossary/glossary.md) | términos AFIP |
+| consumidas | [`docs/consumed/afip.md`](../docs/consumed/afip.md) | SOAP WSAA + WSFE |
+| errores | [`docs/errors/errors.md`](../docs/errors/errors.md) | excepciones + política |
+| configuración | [`docs/config/configuracion.md`](../docs/config/configuracion.md) | opciones runtime |
+| topología | [`docs/topology/topology.md`](../docs/topology/topology.md) | deps + externos |
+| test | [`docs/test/testing.md`](../docs/test/testing.md) | suite + gaps |
+| operaciones (api) · datos · eventos · multi-tenancy | n/a | gema SOAP sin HTTP/DB/eventos |
+
+## Uso correcto / gotchas
+
+- Homologación vs producción se elige por `auth_url`/`service_url` — riesgo de emitir contra prod por error.
+- Errores de negocio de AFIP **no** levantan excepción: se leen en `afip_errors`/`afip_events`/`afip_observations`.
+- La suite RSpec actual está desactualizada respecto al código (ver `docs/test/testing.md`) — no asumir cobertura.

data/skills.yml

@@ -0,0 +1,17 @@
+mcps:
+  - github
+  - clickup
+skills:
+  multi-vendor-feedback:
+  yard:
+  quality-code:
+  gem-release:
+  arch-structure:
+  arch-compose:
+  arch-enrich:
+  skill-feedback:
+  agent-issue:
+  bug-report:
+  dev-flow:
+  documentation-writer:
+  matrix-element:

data/snoopy_afip.gemspec

@@ -7,9 +7,8 @@ Gem::Specification.new do |s|
   s.name = "snoopy_afip"
   s.version = Snoopy::VERSION
 
-  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.required_ruby_version = ">= 2.5"
   s.authors = ["g.edera"]
-  s.date = "2017-06-29"
   s.description = "Adaptador para Web Service de Facturación Electrónica Argentina (AFIP)"
   s.email = "gab.edera@gmail.com"
   s.files = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
@@ -18,7 +17,10 @@ Gem::Specification.new do |s|
   s.require_paths = ["lib"]
   # s.rubygems_version = "1.8.25"
   s.summary = "Adaptador AFIP wsfe."
-  s.test_files = ["spec/snoopy_afip/authorizer_spec.rb", "spec/snoopy_afip/bill_spec.rb", "spec/spec_helper.rb"]
+  s.test_files = Dir["spec/**/*"]
 
   s.add_dependency 'savon', '~> 2.12.1'
+
+  s.add_development_dependency 'rspec', '~> 3.13'
+  s.add_development_dependency 'activesupport' # Bill#valid? usa blank?/present?
 end

data/spec/snoopy_afip/authentication_adapter_spec.rb

@@ -0,0 +1,20 @@
+require File.expand_path(File.dirname(__FILE__) + "/../spec_helper")
+
+RSpec.describe Snoopy::AuthenticationAdapter do
+  describe "#build_tra" do
+    it "construye el TRA (loginTicketRequest) para el servicio wsfe" do
+      xml = described_class.new.build_tra
+      expect(xml).to include("loginTicketRequest")
+      expect(xml).to include("wsfe")
+      expect(xml).to include("uniqueId")
+    end
+  end
+
+  describe "credenciales de instancia" do
+    it "expone pkey y cert recibidos" do
+      auth = described_class.new(pkey: "/tmp/pkey", cert: "/tmp/cert")
+      expect(auth.pkey).to eq("/tmp/pkey")
+      expect(auth.cert).to eq("/tmp/cert")
+    end
+  end
+end

data/spec/snoopy_afip/authorize_adapter_spec.rb

@@ -0,0 +1,37 @@
+require File.expand_path(File.dirname(__FILE__) + "/../spec_helper")
+
+RSpec.describe Snoopy::AuthorizeAdapter do
+  subject(:adapter) do
+    described_class.new(bill: nil, cuit: "20111111112", sign: "SIGN", token: "TOKEN",
+                        pkey: "/tmp/pkey", cert: "/tmp/cert")
+  end
+
+  describe "#auth" do
+    it "arma el hash de credenciales para AFIP" do
+      expect(adapter.auth).to eq("Token" => "TOKEN", "Sign" => "SIGN", "Cuit" => "20111111112")
+    end
+  end
+
+  # Regresión #10/#16: los rescues de parseo registraban con `errors << ...`
+  # sobre un Hash (NoMethodError) y la línea 182 usaba una constante mal
+  # namespaceada (NameError). Ahora registran en @errors un String (.message)
+  # y NO propagan. Se dispara pasando datos malformados (nil) a cada parser.
+  describe "rescues de parseo (no explotan)" do
+    {
+      parse_errors:       :error_parser,
+      parse_events:       :events_parser,
+      parse_observations: :observation_parser
+    }.each do |method, key|
+      it "##{method} con dato inválido registra un String en errors[#{key.inspect}] sin levantar" do
+        expect { adapter.public_send(method, nil) }.not_to raise_error
+        expect(adapter.errors[key]).to be_a(String)
+      end
+    end
+
+    it "parse_fe_comp_consultar_response con response vacío no levanta NameError" do
+      adapter.response = {}
+      expect { adapter.parse_fe_comp_consultar_response }.not_to raise_error
+      expect(adapter.errors[:fecomp_consult_response_parser]).to be_a(String)
+    end
+  end
+end