facturas 0.7.0 → 0.8.0

package/dist/{fiscal-evidence-BQuBbJ3h.d.ts → errors-B0uouRzR.d.ts}

@@ -1,5 +1,80 @@
 import { A as ArcaServiceName } from './types-BXq0da71.js';
 
+/** 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 = "authentication_rejected" | "transport_error" | "soap_fault" | "invalid_response" | "incomplete_response" | "contradictory_response" | "unexpected_error";
+/** Safe authentication evidence attached to an exact authorization outcome. */
+type ArcaAuthenticationEvidence = {
+    code: "ARCA_AUTHENTICATION_ERROR";
+    reason: ArcaAuthenticationReason;
+    providerCode?: string | number;
+};
+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;
+    authentication?: ArcaAuthenticationEvidence;
+    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>;
+};
+
 /** Base error class for all ARCA-related errors. */
 declare class ArcaError extends Error {
     readonly code: string;
@@ -110,80 +185,13 @@ declare class ArcaServiceError extends ArcaError {
         issues?: readonly ArcaFiscalIssue[];
     });
 }
-
-/** 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;
+/** Narrow error evidence: never includes a cause, raw response or stack. */
+type ArcaSafeErrorMetadata = {
+    name: string;
     message: string;
-    resultLevel?: ArcaFiscalResultLevel;
-};
-/** Why an authorization response cannot prove approval or rejection. */
-type ArcaAuthorizationIndeterminateReason = "authentication_rejected" | "transport_error" | "soap_fault" | "invalid_response" | "incomplete_response" | "contradictory_response" | "unexpected_error";
-/** Safe authentication evidence attached to an exact authorization outcome. */
-type ArcaAuthenticationEvidence = {
-    code: "ARCA_AUTHENTICATION_ERROR";
-    reason: ArcaAuthenticationReason;
-    providerCode?: string | number;
-};
-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;
-    authentication?: ArcaAuthenticationEvidence;
-    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>;
+    code?: string;
+    statusCode?: number;
 };
+declare function toArcaSafeErrorMetadata(error: unknown): ArcaSafeErrorMetadata;
 
-export { ArcaAuthenticationError as A, type ArcaAuthenticationErrorOptions as a, type ArcaAuthenticationEvidence as b, type ArcaAuthenticationReason as c, type ArcaAuthorizationIndeterminateReason as d, type ArcaAuthorizationOutcome as e, ArcaConfigurationError as f, ArcaError as g, type ArcaFiscalIssue as h, type ArcaFiscalResultLevel as i, type ArcaFiscalResults as j, type ArcaFiscalService as k, ArcaInputError as l, type ArcaInputErrorCode as m, type ArcaInputErrorOptions as n, ArcaInvalidSoapResponseError as o, ArcaServiceError as p, ArcaSoapFaultError as q, ArcaTransportError as r, type ArcaVoucherLookupResult as s, isArcaAuthenticationError as t };
+export { type ArcaAuthorizationOutcome as A, type ArcaFiscalIssue as a, type ArcaSafeErrorMetadata as b, ArcaAuthenticationError as c, type ArcaAuthenticationErrorOptions as d, type ArcaAuthenticationEvidence as e, type ArcaAuthenticationReason as f, type ArcaAuthorizationIndeterminateReason as g, ArcaConfigurationError as h, ArcaError as i, type ArcaFiscalResultLevel as j, type ArcaFiscalResults as k, type ArcaFiscalService as l, ArcaInputError as m, type ArcaInputErrorCode as n, type ArcaInputErrorOptions as o, ArcaInvalidSoapResponseError as p, ArcaServiceError as q, ArcaSoapFaultError as r, ArcaTransportError as s, type ArcaVoucherLookupResult as t, isArcaAuthenticationError as u, toArcaSafeErrorMetadata as v };

package/dist/errors.d.ts

@@ -1,2 +1,2 @@
 import './types-BXq0da71.js';
-export { A as ArcaAuthenticationError, a as ArcaAuthenticationErrorOptions, c as ArcaAuthenticationReason, f as ArcaConfigurationError, g as ArcaError, l as ArcaInputError, m as ArcaInputErrorCode, n as ArcaInputErrorOptions, o as ArcaInvalidSoapResponseError, p as ArcaServiceError, q as ArcaSoapFaultError, r as ArcaTransportError, t as isArcaAuthenticationError } from './fiscal-evidence-BQuBbJ3h.js';
+export { c as ArcaAuthenticationError, d as ArcaAuthenticationErrorOptions, f as ArcaAuthenticationReason, h as ArcaConfigurationError, i as ArcaError, m as ArcaInputError, n as ArcaInputErrorCode, o as ArcaInputErrorOptions, p as ArcaInvalidSoapResponseError, b as ArcaSafeErrorMetadata, q as ArcaServiceError, r as ArcaSoapFaultError, s as ArcaTransportError, u as isArcaAuthenticationError, v as toArcaSafeErrorMetadata } from './errors-B0uouRzR.js';

package/dist/errors.mjs

@@ -7,8 +7,9 @@ import {
   ArcaServiceError,
   ArcaSoapFaultError,
   ArcaTransportError,
-  isArcaAuthenticationError
-} from "./chunk-MBWOFO67.mjs";
+  isArcaAuthenticationError,
+  toArcaSafeErrorMetadata
+} from "./chunk-HUT3PFKF.mjs";
 export {
   ArcaAuthenticationError,
   ArcaConfigurationError,
@@ -18,6 +19,7 @@ export {
   ArcaServiceError,
   ArcaSoapFaultError,
   ArcaTransportError,
-  isArcaAuthenticationError
+  isArcaAuthenticationError,
+  toArcaSafeErrorMetadata
 };
 //# sourceMappingURL=errors.mjs.map

package/dist/index.d.ts

@@ -2,13 +2,206 @@ import { f as ArcaEnvironment, g as ArcaClientConfig, h as ArcaWsaaSessionStore
 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-BXq0da71.js';
 import { PadronService } from './padron.js';
 export { CreatePadronServiceOptions, PadronTaxIdLookupResult, PadronTaxpayerResult, createPadronService } from './padron.js';
-import { WsfeService } from './wsfe.js';
-export { BuildFacturaBInput, BuildFacturaCInput, CreateWsfeServiceOptions, WsfeActivity, WsfeActivityType, WsfeAssociatedPeriod, WsfeAssociatedVoucher, WsfeAuthorizationOutcome, WsfeAuthorizationResult, WsfeAuthorizeVoucherInput, WsfeBuilderCurrencyInput, WsfeBuilderVatRate, WsfeBuyer, WsfeCatalogEntry, WsfeCurrencyType, WsfeDateInput, WsfeOptionalField, WsfeQuotation, WsfeReceiverVatCondition, WsfeSalesPoint, WsfeServerStatus, WsfeTax, WsfeVatRate, WsfeVoucherInfo, WsfeVoucherInput, WsfeVoucherLookupResult, buildFacturaB, buildFacturaC, createWsfeService } from './wsfe.js';
+import { VoucherClass, ReceiverCondition } from './constants.js';
+export { ARCA_FINAL_CONSUMER_IDENTIFICATION_THRESHOLD_MINOR_UNITS, ARCA_INVOICE_CLASS_BY_ISSUER, ARCA_ISSUER_CONDITION_IDS, ARCA_RECEIVER_CONDITION_IDS, IssuerCondition } from './constants.js';
+import { A as ArcaAuthorizationOutcome, a as ArcaFiscalIssue, b as ArcaSafeErrorMetadata } from './errors-B0uouRzR.js';
+export { c as ArcaAuthenticationError, d as ArcaAuthenticationErrorOptions, e as ArcaAuthenticationEvidence, f as ArcaAuthenticationReason, g as ArcaAuthorizationIndeterminateReason, h as ArcaConfigurationError, i as ArcaError, j as ArcaFiscalResultLevel, k as ArcaFiscalResults, l as ArcaFiscalService, m as ArcaInputError, n as ArcaInputErrorCode, o as ArcaInputErrorOptions, p as ArcaInvalidSoapResponseError, q as ArcaServiceError, r as ArcaSoapFaultError, s as ArcaTransportError, t as ArcaVoucherLookupResult, u as isArcaAuthenticationError, v as toArcaSafeErrorMetadata } from './errors-B0uouRzR.js';
+import { S as SupportedVatRate, W as WsfeVoucherInput, a as WsfeVoucherInfo, b as WsfeDateInput, c as WsfeService } from './wsfe-CG_erq7V.js';
+export { B as BuildFacturaBInput, d as BuildFacturaCInput, C as CreateWsfeServiceOptions, e as WsfeActivity, f as WsfeActivityType, g as WsfeAssociatedPeriod, h as WsfeAssociatedVoucher, i as WsfeAuthorizationOutcome, j as WsfeAuthorizationResult, k as WsfeAuthorizeVoucherInput, l as WsfeBuilderCurrencyInput, m as WsfeBuilderVatRate, n as WsfeBuyer, o as WsfeCatalogEntry, p as WsfeCurrencyType, q as WsfeOptionalField, r as WsfeQuotation, s as WsfeReceiverVatCondition, t as WsfeSalesPoint, u as WsfeServerStatus, v as WsfeTax, w as WsfeVatRate, x as WsfeVoucherLookupResult, y as buildFacturaB, z as buildFacturaC, A as createWsfeService } from './wsfe-CG_erq7V.js';
 import { WsmtxcaService } from './wsmtxca.js';
 export { CreateWsmtxcaServiceOptions, WsmtxcaAuthorizationOutcome, WsmtxcaAuthorizationResult, WsmtxcaAuthorizeVoucherInput, WsmtxcaLastAuthorizedVoucherResult, WsmtxcaSalesPoint, WsmtxcaSalesPointsResult, WsmtxcaVoucherInfo, WsmtxcaVoucherLookupOutcome, WsmtxcaVoucherLookupResult, createWsmtxcaService } from './wsmtxca.js';
-export { A as ArcaAuthenticationError, a as ArcaAuthenticationErrorOptions, b as ArcaAuthenticationEvidence, c as ArcaAuthenticationReason, d as ArcaAuthorizationIndeterminateReason, e as ArcaAuthorizationOutcome, f as ArcaConfigurationError, g as ArcaError, h as ArcaFiscalIssue, i as ArcaFiscalResultLevel, j as ArcaFiscalResults, k as ArcaFiscalService, l as ArcaInputError, m as ArcaInputErrorCode, n as ArcaInputErrorOptions, o as ArcaInvalidSoapResponseError, p as ArcaServiceError, q as ArcaSoapFaultError, r as ArcaTransportError, s as ArcaVoucherLookupResult, t as isArcaAuthenticationError } from './fiscal-evidence-BQuBbJ3h.js';
 import './index-CVpygFb0.js';
 
+type VatRate = SupportedVatRate | "exempt" | "untaxed";
+type VatItem = {
+    net: number;
+    gross?: never;
+    amount?: never;
+    vat: VatRate;
+} | {
+    gross: number;
+    net?: never;
+    amount?: never;
+    vat: VatRate;
+};
+type AmountItem = {
+    amount: number;
+    vat?: never;
+    net?: never;
+    gross?: never;
+};
+type IssueAmounts = {
+    computedTotal: number;
+    sentTotal: number;
+    vatAdjustment: number;
+};
+
+type VoucherCoordinates = {
+    salesPoint: number;
+    voucherType: number;
+    number: number;
+};
+/** Raw-free consultation evidence. Missing provider fields remain absent. */
+type VoucherSummary = {
+    number: number;
+    salesPoint?: number;
+    voucherType?: number;
+    date?: string;
+    concept?: number;
+    documentType?: number;
+    documentNumber?: string;
+    receiverVatConditionId?: number;
+    currencyId?: string;
+    exchangeRate?: number;
+    totalAmount?: number;
+    netAmount?: number;
+    vatAmount?: number;
+    exemptAmount?: number;
+    nonTaxableAmount?: number;
+    taxAmount?: number;
+    vatRates?: {
+        id: number;
+        baseAmount: number;
+        amount: number;
+    }[];
+    serviceStartDate?: string;
+    serviceEndDate?: string;
+    paymentDueDate?: string;
+    result?: string;
+    cae?: string;
+    caeExpiry?: string;
+};
+type WsfeIdentityMatch = {
+    matches: true;
+} | {
+    matches: false;
+    evidence: "conflict" | "incomplete";
+    reason: string;
+};
+/**
+ * Compares the invoice subset supported by vouchers.issue(). This proves
+ * consistency, not authorship; callers must serialize writers per taxpayer,
+ * sales point and voucher type. Unsupported exact-API extensions are incomplete.
+ */
+declare function matchWsfeVoucherIdentity(sent: WsfeVoucherInput, number: number, found: WsfeVoucherInfo): WsfeIdentityMatch;
+
+type IssueOptions = {
+    representedTaxId?: number | string;
+    forceRefresh?: boolean;
+    include?: {
+        raw?: boolean;
+        exactInput?: boolean;
+    };
+};
+type IssuedVoucher = VoucherCoordinates & {
+    voucherClass: VoucherClass;
+    date: string;
+    cae: string;
+    caeExpiry: string;
+    amounts: IssueAmounts;
+};
+type WithRaw<T, O extends IssueOptions> = T & (true extends NonNullable<O["include"]>["raw"] ? {
+    raw?: Record<string, unknown>;
+} : unknown);
+type WithSent<O extends IssueOptions> = O extends {
+    include: {
+        exactInput: true;
+    };
+} ? {
+    sent: WsfeVoucherInput;
+} : true extends NonNullable<O["include"]>["exactInput"] ? {
+    sent?: WsfeVoucherInput;
+} : unknown;
+type Evidence<K extends ArcaAuthorizationOutcome<"wsfe">["kind"], O extends IssueOptions> = WithRaw<Omit<Extract<ArcaAuthorizationOutcome<"wsfe">, {
+    kind: K;
+}>, "raw">, O>;
+/** Fiscal outcomes are returned, never thrown or automatically resubmitted. */
+type IssueOutcome<O extends IssueOptions = {
+    include?: never;
+}> = ({
+    kind: "authorized";
+    recoveredByMatch: false;
+    voucher: IssuedVoucher;
+    authorization: Evidence<"authorized", O>;
+} & WithSent<O>) | ({
+    kind: "authorized";
+    recoveredByMatch: true;
+    voucher: IssuedVoucher;
+    attempt: Evidence<"indeterminate", O>;
+    lookup: WithRaw<VoucherSummary, O>;
+} & WithSent<O>) | {
+    kind: "rejected";
+    attempted: VoucherCoordinates;
+    issues: ArcaFiscalIssue[];
+    authorization: Evidence<"rejected", O>;
+} | {
+    kind: "indeterminate";
+    attempted: VoucherCoordinates;
+    attempt: Evidence<"indeterminate", O>;
+    lookup: WithRaw<{
+        kind: "not_found";
+    }, O> | WithRaw<{
+        kind: "incomplete";
+        reason: string;
+    }, O> | {
+        kind: "failed";
+        error: ArcaSafeErrorMetadata;
+    };
+} | {
+    kind: "conflict";
+    attempted: VoucherCoordinates;
+    attempt: Evidence<"indeterminate", O>;
+    found: WithRaw<VoucherSummary, O>;
+    reason: string;
+};
+
+type Receiver = {
+    condition: "consumidor_final";
+    cuit?: number | string;
+    dni?: number | string;
+} | {
+    condition: Exclude<ReceiverCondition, "consumidor_final">;
+    cuit: number | string;
+    dni?: never;
+};
+type IssueCommon = {
+    salesPoint: number;
+    to: Receiver;
+    total?: number;
+    date?: WsfeDateInput;
+    currency?: "ARS" | "USD";
+    exchangeRate?: string;
+    service?: {
+        from: WsfeDateInput;
+        to: WsfeDateInput;
+        dueDate: WsfeDateInput;
+    };
+};
+type IssueInput = IssueCommon & ({
+    issuer: "responsable_inscripto";
+    items: readonly VatItem[];
+} | {
+    issuer: "monotributo" | "exento" | "no_alcanzado";
+    items: readonly AmountItem[];
+});
+
+type VouchersService = {
+    /**
+     * Single-writer contract: serialize calls per (representedTaxId, salesPoint,
+     * voucherType), including concurrent promises in one process. The SDK does not
+     * coordinate writers; uncoordinated calls collide on ARCA 10016. Servers and
+     * queues must persist attempts and use wsfe.authorizeVoucherOutcome() directly.
+     * See the "does not serialize concurrent calls" test in services/vouchers.test.ts.
+     *
+     * One next-number read, one authorization attempt (zero transport retries), and
+     * at most one identity-matched lookup after indeterminate. Never resubmits.
+     * Local validation and next-number read failures throw before authorization.
+     */
+    issue<O extends IssueOptions = {
+        include?: never;
+    }>(input: IssueInput, options?: O): Promise<IssueOutcome<O>>;
+};
+
 /** Immutable, credential-free operational view of an ARCA client configuration. */
 type ArcaClientConfigView = Readonly<{
     taxId: string;
@@ -21,13 +214,14 @@ type ArcaClientConfigView = Readonly<{
 type ArcaClient = {
     readonly config: ArcaClientConfigView;
     wsfe: WsfeService;
+    vouchers: VouchersService;
     wsmtxca: WsmtxcaService;
     padron: PadronService;
 };
 /**
  * Creates an ARCA client from the given configuration.
  * Validates the config, wires WSAA authentication and SOAP transport,
- * and returns an object with `.wsfe`, `.wsmtxca`, and `.padron` service modules.
+ * and returns an object with `.vouchers`, `.wsfe`, `.wsmtxca`, and `.padron` service modules.
  *
  * @throws {ArcaConfigurationError} When the config is missing or invalid.
  */
@@ -67,4 +261,4 @@ declare function assertArcaClientConfig(config: ArcaClientConfig): void;
 
 declare function createMemoryWsaaSessionStore(): ArcaWsaaSessionStore;
 
-export { ARCA_ENVIRONMENTS, ARCA_ENV_VARIABLES, type ArcaClient, ArcaClientConfig, type ArcaClientConfigView, ArcaEnvironment, ArcaWsaaSessionStore, type CreateArcaClientConfigFromEnvOptions, PadronService, WsfeService, WsmtxcaService, assertArcaClientConfig, createArcaClient, createArcaClientConfigFromEnv, createMemoryWsaaSessionStore, resolveArcaEnvironment };
+export { ARCA_ENVIRONMENTS, ARCA_ENV_VARIABLES, type AmountItem, ArcaAuthorizationOutcome, type ArcaClient, ArcaClientConfig, type ArcaClientConfigView, ArcaEnvironment, ArcaFiscalIssue, ArcaSafeErrorMetadata, ArcaWsaaSessionStore, type CreateArcaClientConfigFromEnvOptions, type IssueAmounts, type IssueCommon, type IssueInput, type IssueOptions, type IssueOutcome, type IssuedVoucher, PadronService, type Receiver, ReceiverCondition, type VatItem, type VatRate, VoucherClass, type VoucherCoordinates, type VoucherSummary, type VouchersService, WsfeDateInput, type WsfeIdentityMatch, WsfeService, WsfeVoucherInfo, WsfeVoucherInput, WsmtxcaService, assertArcaClientConfig, createArcaClient, createArcaClientConfigFromEnv, createMemoryWsaaSessionStore, matchWsfeVoucherIdentity, resolveArcaEnvironment };