facturas 0.8.0 → 0.10.0

package/dist/index.d.ts

@@ -1,16 +1,16 @@
-import { f as ArcaEnvironment, g as ArcaClientConfig, h as ArcaWsaaSessionStore } from './types-BXq0da71.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-BXq0da71.js';
+import { f as ArcaEnvironment, g as ArcaClientOptions, h as ArcaClientConfig, i as ArcaStore, j as ArcaWsaaSessionStore } from './types-BiznC1-X.js';
+export { e as ArcaAuthCredentials, d as ArcaAuthOptions, k as ArcaLogLevel, l as ArcaLoggerConfig, m as ArcaPadronServiceName, n as ArcaRepresentedTaxId, A as ArcaServiceName, o as ArcaServiceTarget, c as ArcaWsaaServiceId, p as ArcaWsaaSessionKey } from './types-BiznC1-X.js';
 import { PadronService } from './padron.js';
 export { CreatePadronServiceOptions, PadronTaxIdLookupResult, PadronTaxpayerResult, createPadronService } from './padron.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 { A as ArcaAuthorizationOutcome, a as ArcaFiscalIssue, b as ArcaSafeErrorMetadata } from './fiscal-evidence-DBzakqBE.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 './fiscal-evidence-DBzakqBE.js';
+import { S as SupportedVatRate, W as WsfeVoucherInput, a as WsfeVoucherInfo, b as WsfeDateInput, c as WsfeService } from './wsfe-DDY9E1GJ.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 WsfeAuthorizeVoucherInput, k as WsfeBuilderCurrencyInput, l as WsfeBuilderVatRate, m as WsfeBuyer, n as WsfeCatalogEntry, o as WsfeCurrencyType, p as WsfeOptionalField, q as WsfeQuotation, r as WsfeReceiverVatCondition, s as WsfeSalesPoint, t as WsfeServerStatus, u as WsfeTax, v as WsfeVatRate, w as WsfeVoucherLookupResult, x as buildFacturaB, y as buildFacturaC, z as createWsfeService } from './wsfe-DDY9E1GJ.js';
 import { WsmtxcaService } from './wsmtxca.js';
-export { CreateWsmtxcaServiceOptions, WsmtxcaAuthorizationOutcome, WsmtxcaAuthorizationResult, WsmtxcaAuthorizeVoucherInput, WsmtxcaLastAuthorizedVoucherResult, WsmtxcaSalesPoint, WsmtxcaSalesPointsResult, WsmtxcaVoucherInfo, WsmtxcaVoucherLookupOutcome, WsmtxcaVoucherLookupResult, createWsmtxcaService } from './wsmtxca.js';
-import './index-CVpygFb0.js';
+export { CreateWsmtxcaServiceOptions, WsmtxcaAuthorizationOutcome, WsmtxcaAuthorizeVoucherInput, WsmtxcaLastAuthorizedVoucherResult, WsmtxcaSalesPoint, WsmtxcaSalesPointsResult, WsmtxcaVoucherInfo, WsmtxcaVoucherLookupOutcome, WsmtxcaVoucherLookupResult, createWsmtxcaService } from './wsmtxca.js';
+import './index-CVGQyyYM.js';
 
 type VatRate = SupportedVatRate | "exempt" | "untaxed";
 type VatItem = {
@@ -79,13 +79,14 @@ type WsfeIdentityMatch = {
     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.
+ * Compares the invoice subset supported by issue(). This proves
+ * consistency, not authorship. Configure a store and pass idempotencyKey for retries.
+ * Unsupported exact-API extensions are incomplete.
  */
 declare function matchWsfeVoucherIdentity(sent: WsfeVoucherInput, number: number, found: WsfeVoucherInfo): WsfeIdentityMatch;
 
 type IssueOptions = {
+    idempotencyKey?: string;
     representedTaxId?: number | string;
     forceRefresh?: boolean;
     include?: {
@@ -100,6 +101,16 @@ type IssuedVoucher = VoucherCoordinates & {
     caeExpiry: string;
     amounts: IssueAmounts;
 };
+/**
+ * What issue() would send, derived with zero I/O. The voucher number is absent
+ * because it is only known when the number is reserved at issuance.
+ */
+type IssuePreview = {
+    voucherClass: VoucherClass;
+    voucherType: number;
+    amounts: IssueAmounts;
+    request: WsfeVoucherInput;
+};
 type WithRaw<T, O extends IssueOptions> = T & (true extends NonNullable<O["include"]>["raw"] ? {
     raw?: Record<string, unknown>;
 } : unknown);
@@ -115,7 +126,7 @@ type WithSent<O extends IssueOptions> = O extends {
 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. */
+/** Fiscal outcomes are returned. Keyed replays authorize only after not_found. */
 type IssueOutcome<O extends IssueOptions = {
     include?: never;
 }> = ({
@@ -185,21 +196,61 @@ type IssueInput = IssueCommon & ({
     items: readonly AmountItem[];
 });
 
+/**
+ * The credited lines and, at most, the note's own sales point and date.
+ * Class, receiver, currency, concept and service dates come from the original.
+ *
+ * The mode is explicit: `items` credits the chosen lines, `all: true` credits
+ * the whole original. A forgotten field never credits the whole invoice.
+ */
+type CreditNoteInput = {
+    /** The authorized invoice the note corrects. */
+    for: VoucherCoordinates;
+    salesPoint?: number;
+    date?: WsfeDateInput;
+} & ({
+    items: IssueInput["items"];
+    total?: number;
+    all?: never;
+} | {
+    all: true;
+    items?: never;
+    total?: never;
+});
+
 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.
+     * Issues a credit note against an authorized A, B or C invoice. The note
+     * credits the chosen `items`, or the whole original with `all: true`.
      *
-     * One next-number read, one authorization attempt (zero transport retries), and
-     * at most one identity-matched lookup after indeterminate. Never resubmits.
+     * Everything except the credited lines, the note's sales point and its date
+     * comes from the original: class, receiver, currency, concept and service
+     * dates. ARCA has no cancellation; both modes write a real fiscal document.
+     */
+    issueCreditNote<O extends IssueOptions = {
+        include?: never;
+    }>(input: CreditNoteInput, options?: O): Promise<IssueOutcome<O>>;
+    /**
+     * Configure a store and pass idempotencyKey to recover retries after a crash.
+     *
+     * Without a key: one next-number read, one authorization and at most one lookup.
+     * Keyed replay consults the reserved number; only not_found permits a write.
      * Local validation and next-number read failures throw before authorization.
      */
     issue<O extends IssueOptions = {
         include?: never;
     }>(input: IssueInput, options?: O): Promise<IssueOutcome<O>>;
+    /**
+     * Derives what issue() would send for the same input, with no I/O at all:
+     * no store, no WSAA, no SOAP and no next-number read.
+     *
+     * It throws every input error issue() throws before its first call, so a
+     * caller that previews and then issues sees no new local error.
+     */
+    preview(input: IssueInput, options?: PreviewOptions): IssuePreview;
+};
+type PreviewOptions = {
+    representedTaxId?: number | string;
 };
 
 /** Immutable, credential-free operational view of an ARCA client configuration. */
@@ -213,19 +264,24 @@ type ArcaClientConfigView = Readonly<{
 /** Fully wired ARCA client with access to all service modules. */
 type ArcaClient = {
     readonly config: ArcaClientConfigView;
+    /** Issues an invoice from business input. Idempotent with a store and key. */
+    issue: VouchersService["issue"];
+    /** Derives what issue() would send for the same input, with no I/O. */
+    preview: VouchersService["preview"];
+    /** Issues a credit note against an authorized invoice, partial or full. */
+    issueCreditNote: VouchersService["issueCreditNote"];
     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 `.vouchers`, `.wsfe`, `.wsmtxca`, and `.padron` service modules.
+ * and returns an object with `issue()`, `preview()`, `issueCreditNote()` and the `.wsfe`, `.wsmtxca`, and `.padron` service modules.
  *
  * @throws {ArcaConfigurationError} When the config is missing or invalid.
  */
-declare function createArcaClient(config: ArcaClientConfig): ArcaClient;
+declare function createArcaClient(config?: ArcaClientOptions): ArcaClient;
 
 /** Valid ARCA environment names. */
 declare const ARCA_ENVIRONMENTS: readonly ["production", "test"];
@@ -259,6 +315,35 @@ declare function createArcaClientConfigFromEnv(options?: CreateArcaClientConfigF
  */
 declare function assertArcaClientConfig(config: ArcaClientConfig): void;
 
+/** Persistent store for a single server with a private durable volume. */
+declare function createFileStore(directory: string): ArcaStore;
+
+/** In-process store for tests; reservations do not survive a restart. */
+declare function createMemoryStore(): ArcaStore;
+
+type Row = {
+    key?: string;
+    value?: string;
+};
+/** Uses the caller's SQL client; provision the table before use. */
+declare function createPostgresStore({ query, table, }: {
+    query: (text: string, params: string[]) => Promise<Row[] | {
+        rows: Row[];
+    }>;
+    table?: string;
+}): ArcaStore;
+
+type RedisClient = {
+    get(key: string): Promise<unknown>;
+    set(key: string, value: string): Promise<unknown>;
+    call?(...args: string[]): Promise<unknown>;
+    del?(key: string): Promise<unknown>;
+};
+/** Uses ioredis or Upstash without importing either driver. */
+declare function createRedisStore(client: RedisClient, options?: {
+    flavor?: "ioredis" | "upstash";
+}): ArcaStore;
+
 declare function createMemoryWsaaSessionStore(): ArcaWsaaSessionStore;
 
-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 };
+export { ARCA_ENVIRONMENTS, ARCA_ENV_VARIABLES, type AmountItem, ArcaAuthorizationOutcome, type ArcaClient, ArcaClientOptions as ArcaClientConfig, type ArcaClientConfigView, ArcaEnvironment, ArcaFiscalIssue, ArcaSafeErrorMetadata, ArcaStore, ArcaWsaaSessionStore, type CreateArcaClientConfigFromEnvOptions, type CreditNoteInput, type IssueAmounts, type IssueCommon, type IssueInput, type IssueOptions, type IssueOutcome, type IssuePreview, 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, createFileStore, createMemoryStore, createMemoryWsaaSessionStore, createPostgresStore, createRedisStore, matchWsfeVoucherIdentity, resolveArcaEnvironment };