facturas 0.5.1 → 0.6.0

package/README.md

@@ -16,8 +16,8 @@ npm install facturas
 
 For the full quick start, troubleshooting, and examples, see the repository docs:
 
-- [Repository README](https://github.com/LaPyme/arca.ts#readme)
-- [Examples directory](https://github.com/LaPyme/arca.ts/tree/main/examples)
+- [Repository README](https://github.com/LaPyme/facturas#readme)
+- [Examples directory](https://github.com/LaPyme/facturas/tree/main/examples)
 
 The package exports:
 
@@ -33,6 +33,8 @@ The package exports:
 
 Authenticated WSFE and WSMTXCA methods accept `forceRefresh: true` when callers need to discard the cached WSAA TA and request a fresh Token Authorization for the same service.
 
+For durable fiscal workflows, `authorizeVoucherOutcome(...)` returns typed `authorized`, `rejected`, or `indeterminate` evidence and performs one authorization transport attempt. `lookupVoucher(...)` provides operation-scoped `found` or `not_found` recovery evidence. The existing `authorizeVoucher(...)`, `getVoucherInfo(...)`, and `getVoucher(...)` methods remain compatibility wrappers.
+
 ## WSFE associated periods
 
 `client.wsfe.createNextVoucher({ data })` supports `associatedPeriod` for credit/debit notes that use `PeriodoAsoc` instead of `CbtesAsoc`:

package/dist/{constants.js → constants.mjs}

@@ -33,4 +33,4 @@ export {
   ARCA_VAT_RATES,
   ARCA_VOUCHER_TYPES
 };
-//# sourceMappingURL=constants.js.map
+//# sourceMappingURL=constants.mjs.map

package/dist/errors.d.ts

@@ -1,4 +1,5 @@
-import { A as ArcaServiceName } from './types-CKKe1Oo4.js';
+import { A as ArcaServiceName } from './types-Cup-oevW.js';
+import { A as ArcaFiscalResultLevel, a as ArcaFiscalResults, b as ArcaFiscalIssue } from './fiscal-evidence-DbbFH74x.js';
 
 /** Base error class for all ARCA-related errors. */
 declare class ArcaError extends Error {
@@ -67,9 +68,23 @@ declare class ArcaInvalidSoapResponseError extends ArcaError {
 declare class ArcaServiceError extends ArcaError {
     readonly name: string;
     readonly serviceCode?: string | number;
+    readonly service?: ArcaServiceName;
+    readonly operation?: string;
+    readonly result?: string;
+    readonly resultLevel?: ArcaFiscalResultLevel;
+    readonly results?: ArcaFiscalResults;
+    readonly cae?: string;
+    readonly issues?: readonly ArcaFiscalIssue[];
     readonly detail?: unknown;
     constructor(message: string, options?: ErrorOptions & {
         serviceCode?: string | number;
+        service?: ArcaServiceName;
+        operation?: string;
+        result?: string;
+        resultLevel?: ArcaFiscalResultLevel;
+        results?: ArcaFiscalResults;
+        cae?: string;
+        issues?: readonly ArcaFiscalIssue[];
         detail?: unknown;
     });
 }

package/dist/{errors.js → errors.mjs}

@@ -68,10 +68,24 @@ var ArcaInvalidSoapResponseError = class extends ArcaError {
 var ArcaServiceError = class extends ArcaError {
   name = "ArcaServiceError";
   serviceCode;
+  service;
+  operation;
+  result;
+  resultLevel;
+  results;
+  cae;
+  issues;
   detail;
   constructor(message, options) {
     super(message, "ARCA_SERVICE_ERROR", options);
     this.serviceCode = options?.serviceCode;
+    this.service = options?.service;
+    this.operation = options?.operation;
+    this.result = options?.result;
+    this.resultLevel = options?.resultLevel;
+    this.results = options?.results;
+    this.cae = options?.cae;
+    this.issues = options?.issues;
     this.detail = options?.detail;
   }
 };
@@ -84,4 +98,4 @@ export {
   ArcaSoapFaultError,
   ArcaTransportError
 };
-//# sourceMappingURL=errors.js.map
+//# sourceMappingURL=errors.mjs.map

package/dist/errors.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts"],"sourcesContent":["import type { ArcaServiceName } from \"./internal/types\";\nimport type {\n  ArcaFiscalIssue,\n  ArcaFiscalResultLevel,\n  ArcaFiscalResults,\n} from \"./services/fiscal-evidence\";\n\n/** Base error class for all ARCA-related errors. */\nexport class ArcaError extends Error {\n  readonly code: string;\n  override readonly name: string = \"ArcaError\";\n\n  constructor(message: string, code = \"ARCA_ERROR\", options?: ErrorOptions) {\n    super(message, options);\n    this.code = code;\n  }\n}\n\n/** Thrown when the ARCA client configuration is missing or invalid. */\nexport class ArcaConfigurationError extends ArcaError {\n  override readonly name: string = \"ArcaConfigurationError\";\n\n  constructor(message: string, options?: ErrorOptions) {\n    super(message, \"ARCA_CONFIGURATION_ERROR\", options);\n  }\n}\n\n/** Thrown when caller-provided input data is missing or invalid. */\nexport class ArcaInputError extends ArcaError {\n  override readonly name: string = \"ArcaInputError\";\n  readonly detail?: unknown;\n\n  constructor(\n    message: string,\n    options?: ErrorOptions & {\n      detail?: unknown;\n    }\n  ) {\n    super(message, \"ARCA_INPUT_ERROR\", options);\n    this.detail = options?.detail;\n  }\n}\n\n/** Thrown when an HTTP request to an ARCA endpoint fails at the transport level. */\nexport class ArcaTransportError extends ArcaError {\n  override readonly name: string = \"ArcaTransportError\";\n  readonly statusCode?: number;\n  readonly contentType?: string;\n  readonly responseBody?: string;\n\n  constructor(\n    message: string,\n    options?: ErrorOptions & {\n      statusCode?: number;\n      contentType?: string;\n      responseBody?: string;\n    }\n  ) {\n    super(message, \"ARCA_TRANSPORT_ERROR\", options);\n    this.statusCode = options?.statusCode;\n    this.contentType = options?.contentType;\n    this.responseBody = options?.responseBody;\n  }\n}\n\n/** Thrown when the SOAP response contains a Fault element. */\nexport class ArcaSoapFaultError extends ArcaError {\n  override readonly name: string = \"ArcaSoapFaultError\";\n  readonly faultCode?: string;\n  readonly detail?: unknown;\n\n  constructor(\n    message: string,\n    options?: ErrorOptions & {\n      faultCode?: string;\n      detail?: unknown;\n    }\n  ) {\n    super(message, \"ARCA_SOAP_FAULT\", options);\n    this.faultCode = options?.faultCode;\n    this.detail = options?.detail;\n  }\n}\n\n/** Thrown when a response cannot be parsed as a valid SOAP envelope. */\nexport class ArcaInvalidSoapResponseError extends ArcaError {\n  override readonly name: string = \"ArcaInvalidSoapResponseError\";\n  readonly service?: ArcaServiceName;\n  readonly operation?: string;\n  readonly endpointUrl?: string;\n  readonly statusCode?: number;\n  readonly contentType?: string;\n  readonly responseBodyLength?: number;\n  readonly responseBodyPreview?: string;\n  readonly parsedDetail?: unknown;\n\n  constructor(\n    message: string,\n    options?: ErrorOptions & {\n      service?: ArcaServiceName;\n      operation?: string;\n      endpointUrl?: string;\n      statusCode?: number;\n      contentType?: string;\n      responseBodyLength?: number;\n      responseBodyPreview?: string;\n      parsedDetail?: unknown;\n    }\n  ) {\n    super(message, \"ARCA_INVALID_SOAP_RESPONSE\", options);\n    this.service = options?.service;\n    this.operation = options?.operation;\n    this.endpointUrl = options?.endpointUrl;\n    this.statusCode = options?.statusCode;\n    this.contentType = options?.contentType;\n    this.responseBodyLength = options?.responseBodyLength;\n    this.responseBodyPreview = options?.responseBodyPreview;\n    this.parsedDetail = options?.parsedDetail;\n  }\n}\n\n/** Thrown when an ARCA service (WSFE, WSMTXCA, Padron) returns a domain-level error. */\nexport class ArcaServiceError extends ArcaError {\n  override readonly name: string = \"ArcaServiceError\";\n  readonly serviceCode?: string | number;\n  readonly service?: ArcaServiceName;\n  readonly operation?: string;\n  readonly result?: string;\n  readonly resultLevel?: ArcaFiscalResultLevel;\n  readonly results?: ArcaFiscalResults;\n  readonly cae?: string;\n  readonly issues?: readonly ArcaFiscalIssue[];\n  readonly detail?: unknown;\n\n  constructor(\n    message: string,\n    options?: ErrorOptions & {\n      serviceCode?: string | number;\n      service?: ArcaServiceName;\n      operation?: string;\n      result?: string;\n      resultLevel?: ArcaFiscalResultLevel;\n      results?: ArcaFiscalResults;\n      cae?: string;\n      issues?: readonly ArcaFiscalIssue[];\n      detail?: unknown;\n    }\n  ) {\n    super(message, \"ARCA_SERVICE_ERROR\", options);\n    this.serviceCode = options?.serviceCode;\n    this.service = options?.service;\n    this.operation = options?.operation;\n    this.result = options?.result;\n    this.resultLevel = options?.resultLevel;\n    this.results = options?.results;\n    this.cae = options?.cae;\n    this.issues = options?.issues;\n    this.detail = options?.detail;\n  }\n}\n"],"mappings":";AAQO,IAAM,YAAN,cAAwB,MAAM;AAAA,EAC1B;AAAA,EACS,OAAe;AAAA,EAEjC,YAAY,SAAiB,OAAO,cAAc,SAAwB;AACxE,UAAM,SAAS,OAAO;AACtB,SAAK,OAAO;AAAA,EACd;AACF;AAGO,IAAM,yBAAN,cAAqC,UAAU;AAAA,EAClC,OAAe;AAAA,EAEjC,YAAY,SAAiB,SAAwB;AACnD,UAAM,SAAS,4BAA4B,OAAO;AAAA,EACpD;AACF;AAGO,IAAM,iBAAN,cAA6B,UAAU;AAAA,EAC1B,OAAe;AAAA,EACxB;AAAA,EAET,YACE,SACA,SAGA;AACA,UAAM,SAAS,oBAAoB,OAAO;AAC1C,SAAK,SAAS,SAAS;AAAA,EACzB;AACF;AAGO,IAAM,qBAAN,cAAiC,UAAU;AAAA,EAC9B,OAAe;AAAA,EACxB;AAAA,EACA;AAAA,EACA;AAAA,EAET,YACE,SACA,SAKA;AACA,UAAM,SAAS,wBAAwB,OAAO;AAC9C,SAAK,aAAa,SAAS;AAC3B,SAAK,cAAc,SAAS;AAC5B,SAAK,eAAe,SAAS;AAAA,EAC/B;AACF;AAGO,IAAM,qBAAN,cAAiC,UAAU;AAAA,EAC9B,OAAe;AAAA,EACxB;AAAA,EACA;AAAA,EAET,YACE,SACA,SAIA;AACA,UAAM,SAAS,mBAAmB,OAAO;AACzC,SAAK,YAAY,SAAS;AAC1B,SAAK,SAAS,SAAS;AAAA,EACzB;AACF;AAGO,IAAM,+BAAN,cAA2C,UAAU;AAAA,EACxC,OAAe;AAAA,EACxB;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EAET,YACE,SACA,SAUA;AACA,UAAM,SAAS,8BAA8B,OAAO;AACpD,SAAK,UAAU,SAAS;AACxB,SAAK,YAAY,SAAS;AAC1B,SAAK,cAAc,SAAS;AAC5B,SAAK,aAAa,SAAS;AAC3B,SAAK,cAAc,SAAS;AAC5B,SAAK,qBAAqB,SAAS;AACnC,SAAK,sBAAsB,SAAS;AACpC,SAAK,eAAe,SAAS;AAAA,EAC/B;AACF;AAGO,IAAM,mBAAN,cAA+B,UAAU;AAAA,EAC5B,OAAe;AAAA,EACxB;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EAET,YACE,SACA,SAWA;AACA,UAAM,SAAS,sBAAsB,OAAO;AAC5C,SAAK,cAAc,SAAS;AAC5B,SAAK,UAAU,SAAS;AACxB,SAAK,YAAY,SAAS;AAC1B,SAAK,SAAS,SAAS;AACvB,SAAK,cAAc,SAAS;AAC5B,SAAK,UAAU,SAAS;AACxB,SAAK,MAAM,SAAS;AACpB,SAAK,SAAS,SAAS;AACvB,SAAK,SAAS,SAAS;AAAA,EACzB;AACF;","names":[]}

package/dist/fiscal-evidence-DbbFH74x.d.ts

@@ -0,0 +1,69 @@
+/** ARCA services that authorize fiscal vouchers. */
+type ArcaFiscalService = "wsfe" | "wsmtxca";
+/** Location of a structured authorization result in the service response. */
+type ArcaFiscalResultLevel = "header" | "detail" | "operation";
+/** Every structured result field exposed by one provider response. */
+type ArcaFiscalResults = {
+    header?: string;
+    detail?: string;
+    operation?: string;
+};
+/** Source and meaning of one provider issue. */
+type ArcaFiscalIssue = {
+    service: ArcaFiscalService;
+    operation: string;
+    source: "error" | "observation";
+    category: "business" | "infrastructure" | "observation" | "unknown";
+    code?: string;
+    message: string;
+    resultLevel?: ArcaFiscalResultLevel;
+};
+/** Why an authorization response cannot prove approval or rejection. */
+type ArcaAuthorizationIndeterminateReason = "transport_error" | "soap_fault" | "invalid_response" | "incomplete_response" | "contradictory_response" | "unexpected_error";
+type ArcaAuthorizationEvidenceBase<TService extends ArcaFiscalService = ArcaFiscalService> = {
+    service: TService;
+    operation: string;
+    results: ArcaFiscalResults;
+    errors: ArcaFiscalIssue[];
+    observations: ArcaFiscalIssue[];
+    raw?: Record<string, unknown>;
+};
+/** Structured evidence returned by one exact voucher authorization attempt. */
+type ArcaAuthorizationOutcome<TService extends ArcaFiscalService = ArcaFiscalService> = (ArcaAuthorizationEvidenceBase<TService> & {
+    kind: "authorized";
+    result: "A" | "O";
+    resultLevel: ArcaFiscalResultLevel;
+    cae: string;
+    caeExpiry?: string;
+    voucherNumber: number;
+}) | (ArcaAuthorizationEvidenceBase<TService> & {
+    kind: "rejected";
+    result: "R";
+    resultLevel: ArcaFiscalResultLevel;
+}) | (ArcaAuthorizationEvidenceBase<TService> & {
+    kind: "indeterminate";
+    reason: ArcaAuthorizationIndeterminateReason;
+    result?: string;
+    resultLevel?: ArcaFiscalResultLevel;
+    cae?: string;
+    caeExpiry?: string;
+    voucherNumber?: number;
+});
+/** Structured result of consulting one exact voucher number. */
+type ArcaVoucherLookupResult<TVoucher, TService extends ArcaFiscalService = ArcaFiscalService> = {
+    kind: "found";
+    service: TService;
+    operation: string;
+    voucher: TVoucher;
+    observations: ArcaFiscalIssue[];
+    raw: Record<string, unknown>;
+} | {
+    kind: "not_found";
+    service: TService;
+    operation: string;
+    errors: ArcaFiscalIssue[];
+    observations: ArcaFiscalIssue[];
+    raw: Record<string, unknown>;
+};
+
+export type { ArcaFiscalResultLevel as A, ArcaFiscalResults as a, ArcaFiscalIssue as b, ArcaAuthorizationIndeterminateReason as c, ArcaAuthorizationOutcome as d, ArcaFiscalService as e, ArcaVoucherLookupResult as f };

package/dist/{index-CqXVyU0E.d.ts → index-3fdgJ3c2.d.ts}

@@ -1,4 +1,4 @@
-import { a as ArcaSoapExecutionOptions, b as ArcaSoapResponse, c as ArcaWsaaServiceId, d as ArcaAuthOptions, e as ArcaAuthCredentials } from './types-CKKe1Oo4.js';
+import { a as ArcaSoapExecutionOptions, b as ArcaSoapResponse, c as ArcaWsaaServiceId, d as ArcaAuthOptions, e as ArcaAuthCredentials } from './types-Cup-oevW.js';
 
 type SoapTransport = {
     execute<TBody, TResult>(request: ArcaSoapExecutionOptions<TBody>): Promise<ArcaSoapResponse<TResult>>;

package/dist/index.d.ts

@@ -1,13 +1,14 @@
-import { f as ArcaClientConfig, g as ArcaEnvironment, h as ArcaWsaaSessionStore } from './types-CKKe1Oo4.js';
-export { e as ArcaAuthCredentials, d as ArcaAuthOptions, i as ArcaLogLevel, j as ArcaLoggerConfig, k as ArcaPadronServiceName, l as ArcaRepresentedTaxId, A as ArcaServiceName, m as ArcaServiceTarget, c as ArcaWsaaServiceId, n as ArcaWsaaSessionKey } from './types-CKKe1Oo4.js';
+import { f as ArcaClientConfig, g as ArcaEnvironment, h as ArcaWsaaSessionStore } from './types-Cup-oevW.js';
+export { e as ArcaAuthCredentials, d as ArcaAuthOptions, i as ArcaLogLevel, j as ArcaLoggerConfig, k as ArcaPadronServiceName, l as ArcaRepresentedTaxId, A as ArcaServiceName, m as ArcaServiceTarget, c as ArcaWsaaServiceId, n as ArcaWsaaSessionKey } from './types-Cup-oevW.js';
 import { PadronService } from './padron.js';
 export { CreatePadronServiceOptions, PadronTaxIdLookupResult, PadronTaxpayerResult, createPadronService } from './padron.js';
 import { WsfeService } from './wsfe.js';
-export { CreateWsfeServiceOptions, WsfeActivity, WsfeActivityType, WsfeAssociatedPeriod, WsfeAssociatedVoucher, WsfeAuthorizationResult, WsfeAuthorizeVoucherInput, WsfeBuyer, WsfeCatalogEntry, WsfeCurrencyType, WsfeDateInput, WsfeOptionalField, WsfeQuotation, WsfeReceiverVatCondition, WsfeSalesPoint, WsfeServerStatus, WsfeTax, WsfeVatRate, WsfeVoucherInfo, WsfeVoucherInput, createWsfeService } from './wsfe.js';
+export { CreateWsfeServiceOptions, WsfeActivity, WsfeActivityType, WsfeAssociatedPeriod, WsfeAssociatedVoucher, WsfeAuthorizationOutcome, WsfeAuthorizationResult, WsfeAuthorizeVoucherInput, WsfeBuyer, WsfeCatalogEntry, WsfeCurrencyType, WsfeDateInput, WsfeOptionalField, WsfeQuotation, WsfeReceiverVatCondition, WsfeSalesPoint, WsfeServerStatus, WsfeTax, WsfeVatRate, WsfeVoucherInfo, WsfeVoucherInput, WsfeVoucherLookupResult, createWsfeService } from './wsfe.js';
 import { WsmtxcaService } from './wsmtxca.js';
-export { CreateWsmtxcaServiceOptions, WsmtxcaAuthorizationResult, WsmtxcaLastAuthorizedVoucherResult, WsmtxcaVoucherLookupResult, createWsmtxcaService } from './wsmtxca.js';
+export { CreateWsmtxcaServiceOptions, WsmtxcaAuthorizationOutcome, WsmtxcaAuthorizationResult, WsmtxcaAuthorizeVoucherInput, WsmtxcaLastAuthorizedVoucherResult, WsmtxcaSalesPoint, WsmtxcaSalesPointsResult, WsmtxcaVoucherInfo, WsmtxcaVoucherLookupOutcome, WsmtxcaVoucherLookupResult, createWsmtxcaService } from './wsmtxca.js';
 export { ArcaConfigurationError, ArcaError, ArcaInputError, ArcaInvalidSoapResponseError, ArcaServiceError, ArcaSoapFaultError, ArcaTransportError } from './errors.js';
-import './index-CqXVyU0E.js';
+export { c as ArcaAuthorizationIndeterminateReason, d as ArcaAuthorizationOutcome, b as ArcaFiscalIssue, A as ArcaFiscalResultLevel, a as ArcaFiscalResults, e as ArcaFiscalService, f as ArcaVoucherLookupResult } from './fiscal-evidence-DbbFH74x.js';
+import './index-3fdgJ3c2.js';
 
 /** Fully wired ARCA client with access to all service modules. */
 type ArcaClient = {