@deuriib/dgii-ecf 0.4.0 → 0.5.0

package/dist/index.d.cts

@@ -94,6 +94,12 @@ interface SummaryTrackingStatusResponse {
 interface InvoiceResponse {
     trackId?: string;
     error?: string;
+    /**
+     * Synchronous acknowledgement text. DGII sends this as a singular string on
+     * the general reception endpoint (`recepcion/api/FacturasElectronicas`).
+     */
+    mensaje?: string;
+    /** Tolerated array form used by the RFCE and status endpoints. */
     mensajes?: Mensaje[];
 }
 interface InvoiceSummaryResponse {
@@ -119,8 +125,9 @@ interface InquiryInvoiceSummary {
     mensajes?: Mensaje[];
 }
 interface CommercialApprovalResponse {
-    codigo: '01' | '02';
-    estado: 'Aprobación Comercial Aprobada.' | 'Aprobacion Comercial Rechazada.';
+    /** `1` = approved, `2` = not found / not processed. */
+    codigo: '1' | '2';
+    estado: 'Aprobación comercial aprobada' | 'Aprobación comercial rechazada';
     mensaje: string[];
 }
 interface VoidNCFResponse {
@@ -252,6 +259,10 @@ interface HttpClientOptions {
     policies?: ResiliencePolicies;
     timeoutMs?: number;
     fetchImpl?: typeof fetch;
+    /** Runs before every authenticated request; may refresh credentials. */
+    beforeRequest?: () => Promise<void>;
+    /** Runs on a 401; return `true` to replay the request once. */
+    onUnauthorized?: () => Promise<boolean>;
 }
 interface RequestOptions {
     method?: 'GET' | 'POST';
@@ -262,6 +273,8 @@ interface RequestOptions {
     body?: BodyInit;
     query?: Record<string, string | number | undefined>;
     resource?: string;
+    /** Skip the auth hooks (used by the authentication round-trip itself). */
+    skipAuthHooks?: boolean;
 }
 /** Thin HTTP client over the native `fetch`, wrapped in resilience policies. */
 declare class HttpClient {
@@ -269,17 +282,22 @@ declare class HttpClient {
     private readonly policies;
     private readonly fetchImpl;
     private readonly baseUrl;
+    private readonly beforeRequest;
+    private readonly onUnauthorized;
     constructor(options: HttpClientOptions);
     setToken(token: string): void;
+    getToken(): string | undefined;
     clearToken(): void;
     private buildUrl;
     private authHeaders;
     private readBody;
     private parseResponse;
     request<T>(options: RequestOptions): Promise<Result<T, DgiiError>>;
+    private execute;
     get<T>(path: string, query?: RequestOptions['query'], opts?: {
         absoluteUrl?: boolean;
         resource?: string;
+        skipAuthHooks?: boolean;
     }): Promise<Result<T, DgiiError>>;
     /**
      * POST a signed XML as a multipart `xml` file part. The runtime computes
@@ -288,6 +306,7 @@ declare class HttpClient {
     postMultipart<T>(path: string, fileName: string, xml: string, opts?: {
         absoluteUrl?: boolean;
         resource?: string;
+        skipAuthHooks?: boolean;
     }): Promise<Result<T, DgiiError>>;
 }
 
@@ -357,6 +376,45 @@ declare class Transformer {
     xml2json<T>(xml: string): Result<T, DgiiError>;
 }
 
+/** Every e-CF type code defined by DGII. */
+declare const ECF_TYPE_CODES: readonly ["31", "32", "33", "34", "41", "43", "44", "45", "46", "47"];
+type EcfTypeCode = (typeof ECF_TYPE_CODES)[number];
+/**
+ * Consumption invoices (E32) at or above this amount go to the general
+ * reception endpoint; below it they must be sent as an RFCE summary.
+ */
+declare const CONSUMPTION_SUMMARY_THRESHOLD = "250000";
+interface GeneralReceptionRoute {
+    readonly kind: 'general';
+    readonly endpoint: Endpoint.SendInvoice;
+}
+interface SummaryReceptionRoute {
+    readonly kind: 'summary';
+    readonly endpoint: Endpoint.SendSummary;
+}
+type ReceptionRoute = GeneralReceptionRoute | SummaryReceptionRoute;
+declare const isEcfTypeCode: (value: string) => value is EcfTypeCode;
+/**
+ * Compare two non-negative decimal strings without going through `number`, so
+ * a money amount never picks up binary floating-point error.
+ *
+ * Returns a negative number when `a < b`, zero when equal, positive otherwise.
+ */
+declare const compareDecimal: (a: string, b: string) => number;
+/**
+ * Decide which DGII reception endpoint a signed document belongs to.
+ *
+ * - `<RFCE>` → the consumption-summary reception (`recepcionfc`).
+ * - `<ECF>` with any type other than E32 → the general reception.
+ * - `<ECF>` type E32 at or above RD$250,000 → the general reception.
+ * - `<ECF>` type E32 below RD$250,000 → rejected: DGII only accepts the
+ *   summary form for those, so the caller must run `convertECF32ToRFCE` first.
+ *
+ * The decision reads `TipoeCF` and `MontoTotal` from the signed document, so it
+ * cannot drift from what is actually being transmitted.
+ */
+declare const resolveReceptionRoute: (signedXml: string) => Result<ReceptionRoute, DgiiError>;
+
 /** First 6 chars of the `<SignatureValue>` (DGII security code). */
 declare const getCodeSixDigitfromSignature: (signedXml: string) => Result<string, DgiiError>;
 /** QR URL for a factura de consumo (FC). */
@@ -387,6 +445,13 @@ interface EcfOptions {
     timeoutMs?: number;
     /** Injectable fetch (useful for tests). */
     fetchImpl?: typeof fetch;
+    /**
+     * Refresh the token when its remaining lifetime falls below this window.
+     * Defaults to 5 minutes.
+     */
+    tokenRefreshSkewMs?: number;
+    /** Injectable clock (epoch milliseconds); useful for tests. */
+    now?: () => number;
 }
 /**
  * DGII e-CF client. Every method returns a `Result` — no thrown domain errors.
@@ -397,6 +462,10 @@ declare class ECF {
     private readonly idempotency;
     private readonly credentials;
     private readonly inFlight;
+    private readonly tokenRefreshSkewMs;
+    private readonly now;
+    private tokenExpiresAt;
+    private refreshPromise;
     constructor(credentials: P12ReaderData, environment?: Environment, options?: EcfOptions);
     private buildIdempotencyKey;
     /**
@@ -408,6 +477,17 @@ declare class ECF {
      */
     private submitIdempotent;
     private singleFlight;
+    /**
+     * Refresh the token when it is missing or about to expire.
+     *
+     * A pre-supplied `token` has no known expiry, so it is never refreshed
+     * proactively — only a 401 triggers a re-authentication for it.
+     */
+    private ensureToken;
+    /** Authenticate, coalescing concurrent refreshes into a single round-trip. */
+    private refreshToken;
+    /** Drop the rejected token and authenticate once. Returns `true` on success. */
+    private reauthenticate;
     /** Authenticate against DGII (or a buyer host) and store the bearer token. */
     authenticate(buyerHost?: string): Promise<Result<AuthToken, DgiiError>>;
     private getSeed;
@@ -419,6 +499,15 @@ declare class ECF {
     sendElectronicDocument(signedXml: string, fileName: string, buyerHost?: string): Promise<Result<InvoiceResponse, DgiiError>>;
     /** Submit a signed summary invoice (RFCE). Idempotent like submissions. */
     sendSummary(signedXml: string, fileName: string): Promise<Result<InvoiceSummaryResponse, DgiiError>>;
+    /**
+     * Submit a signed document to the endpoint its own content belongs to.
+     *
+     * Reads the root element, `TipoeCF` and `MontoTotal` from the signed XML and
+     * dispatches to {@link sendSummary} for an RFCE or to
+     * {@link sendElectronicDocument} for an ECF. An E32 below RD$250,000 is
+     * rejected because DGII only accepts the summary form for those.
+     */
+    sendDocument(signedXml: string, fileName: string, buyerHost?: string): Promise<Result<InvoiceResponse | InvoiceSummaryResponse, DgiiError>>;
     statusTrackId(trackId: string): Promise<Result<TrackingStatusResponse, DgiiError>>;
     inquiryStatus(rncEmisor: string, ncfElectronico: string, rncComprador?: string, codigoSeguridad?: string): Promise<Result<InquiryStatusResponse, DgiiError>>;
     trackStatuses(rncEmisor: string, encf: string): Promise<Result<SummaryTrackingStatusResponse[], DgiiError>>;
@@ -438,4 +527,4 @@ declare class ECF {
     voidENCF(signedXml: string, fileName: string): Promise<Result<VoidNCFResponse, DgiiError>>;
 }
 
-export { type AuthToken, BaseUrl, type BaseUrlKey, type CertificateInfo, type CommercialApprovalResponse, type DgiiDocumentType, DgiiError, type DgiiErrorCode, type DgiiErrorContext, type DgiiErrorOptions, type DgiiResult, ECF, type EcfOptions, Endpoint, Environment, HttpClient, type HttpClientOptions, type IdempotencyStore, InMemoryIdempotencyStore, type InMemoryIdempotencyStoreOptions, type InquiryInvoiceSummary, type InquiryStatus, type InquiryStatusCode, type InquiryStatusResponse, type InvoiceResponse, type InvoiceSummaryResponse, type Mensaje, P12Reader, type P12ReaderData, type RequestOptions, type ResilienceOptions, type ResiliencePolicies, SenderReceiverEndpoint, type ServiceDirectoryResponse, Signature, type SummaryTrackingStatusResponse, type TrackStatusCode, TrackStatusEnum, type TrackingStatusResponse, Transformer, type VoidNCFResponse, type XmlCertificateValidation, buildSenderReceiverUrl, buildUrl, convertECF32ToRFCE, createResiliencePolicies, defaultResilienceOptions, extractDgiiErrorMessage, generateEcfQRCodeURL, generateFcQRCodeURL, getCodeSixDigitfromSignature, getCurrentFormattedDate, getCurrentFormattedDateTime, getXmlFromBodyResponse, isRetryableError, isRetryableStatus, roundHalfUpToCents, toDgiiError, validateXMLCertificate };
+export { type AuthToken, BaseUrl, type BaseUrlKey, CONSUMPTION_SUMMARY_THRESHOLD, type CertificateInfo, type CommercialApprovalResponse, type DgiiDocumentType, DgiiError, type DgiiErrorCode, type DgiiErrorContext, type DgiiErrorOptions, type DgiiResult, ECF, ECF_TYPE_CODES, type EcfOptions, type EcfTypeCode, Endpoint, Environment, type GeneralReceptionRoute, HttpClient, type HttpClientOptions, type IdempotencyStore, InMemoryIdempotencyStore, type InMemoryIdempotencyStoreOptions, type InquiryInvoiceSummary, type InquiryStatus, type InquiryStatusCode, type InquiryStatusResponse, type InvoiceResponse, type InvoiceSummaryResponse, type Mensaje, P12Reader, type P12ReaderData, type ReceptionRoute, type RequestOptions, type ResilienceOptions, type ResiliencePolicies, SenderReceiverEndpoint, type ServiceDirectoryResponse, Signature, type SummaryReceptionRoute, type SummaryTrackingStatusResponse, type TrackStatusCode, TrackStatusEnum, type TrackingStatusResponse, Transformer, type VoidNCFResponse, type XmlCertificateValidation, buildSenderReceiverUrl, buildUrl, compareDecimal, convertECF32ToRFCE, createResiliencePolicies, defaultResilienceOptions, extractDgiiErrorMessage, generateEcfQRCodeURL, generateFcQRCodeURL, getCodeSixDigitfromSignature, getCurrentFormattedDate, getCurrentFormattedDateTime, getXmlFromBodyResponse, isEcfTypeCode, isRetryableError, isRetryableStatus, resolveReceptionRoute, roundHalfUpToCents, toDgiiError, validateXMLCertificate };

package/dist/index.d.ts

@@ -94,6 +94,12 @@ interface SummaryTrackingStatusResponse {
 interface InvoiceResponse {
     trackId?: string;
     error?: string;
+    /**
+     * Synchronous acknowledgement text. DGII sends this as a singular string on
+     * the general reception endpoint (`recepcion/api/FacturasElectronicas`).
+     */
+    mensaje?: string;
+    /** Tolerated array form used by the RFCE and status endpoints. */
     mensajes?: Mensaje[];
 }
 interface InvoiceSummaryResponse {
@@ -119,8 +125,9 @@ interface InquiryInvoiceSummary {
     mensajes?: Mensaje[];
 }
 interface CommercialApprovalResponse {
-    codigo: '01' | '02';
-    estado: 'Aprobación Comercial Aprobada.' | 'Aprobacion Comercial Rechazada.';
+    /** `1` = approved, `2` = not found / not processed. */
+    codigo: '1' | '2';
+    estado: 'Aprobación comercial aprobada' | 'Aprobación comercial rechazada';
     mensaje: string[];
 }
 interface VoidNCFResponse {
@@ -252,6 +259,10 @@ interface HttpClientOptions {
     policies?: ResiliencePolicies;
     timeoutMs?: number;
     fetchImpl?: typeof fetch;
+    /** Runs before every authenticated request; may refresh credentials. */
+    beforeRequest?: () => Promise<void>;
+    /** Runs on a 401; return `true` to replay the request once. */
+    onUnauthorized?: () => Promise<boolean>;
 }
 interface RequestOptions {
     method?: 'GET' | 'POST';
@@ -262,6 +273,8 @@ interface RequestOptions {
     body?: BodyInit;
     query?: Record<string, string | number | undefined>;
     resource?: string;
+    /** Skip the auth hooks (used by the authentication round-trip itself). */
+    skipAuthHooks?: boolean;
 }
 /** Thin HTTP client over the native `fetch`, wrapped in resilience policies. */
 declare class HttpClient {
@@ -269,17 +282,22 @@ declare class HttpClient {
     private readonly policies;
     private readonly fetchImpl;
     private readonly baseUrl;
+    private readonly beforeRequest;
+    private readonly onUnauthorized;
     constructor(options: HttpClientOptions);
     setToken(token: string): void;
+    getToken(): string | undefined;
     clearToken(): void;
     private buildUrl;
     private authHeaders;
     private readBody;
     private parseResponse;
     request<T>(options: RequestOptions): Promise<Result<T, DgiiError>>;
+    private execute;
     get<T>(path: string, query?: RequestOptions['query'], opts?: {
         absoluteUrl?: boolean;
         resource?: string;
+        skipAuthHooks?: boolean;
     }): Promise<Result<T, DgiiError>>;
     /**
      * POST a signed XML as a multipart `xml` file part. The runtime computes
@@ -288,6 +306,7 @@ declare class HttpClient {
     postMultipart<T>(path: string, fileName: string, xml: string, opts?: {
         absoluteUrl?: boolean;
         resource?: string;
+        skipAuthHooks?: boolean;
     }): Promise<Result<T, DgiiError>>;
 }
 
@@ -357,6 +376,45 @@ declare class Transformer {
     xml2json<T>(xml: string): Result<T, DgiiError>;
 }
 
+/** Every e-CF type code defined by DGII. */
+declare const ECF_TYPE_CODES: readonly ["31", "32", "33", "34", "41", "43", "44", "45", "46", "47"];
+type EcfTypeCode = (typeof ECF_TYPE_CODES)[number];
+/**
+ * Consumption invoices (E32) at or above this amount go to the general
+ * reception endpoint; below it they must be sent as an RFCE summary.
+ */
+declare const CONSUMPTION_SUMMARY_THRESHOLD = "250000";
+interface GeneralReceptionRoute {
+    readonly kind: 'general';
+    readonly endpoint: Endpoint.SendInvoice;
+}
+interface SummaryReceptionRoute {
+    readonly kind: 'summary';
+    readonly endpoint: Endpoint.SendSummary;
+}
+type ReceptionRoute = GeneralReceptionRoute | SummaryReceptionRoute;
+declare const isEcfTypeCode: (value: string) => value is EcfTypeCode;
+/**
+ * Compare two non-negative decimal strings without going through `number`, so
+ * a money amount never picks up binary floating-point error.
+ *
+ * Returns a negative number when `a < b`, zero when equal, positive otherwise.
+ */
+declare const compareDecimal: (a: string, b: string) => number;
+/**
+ * Decide which DGII reception endpoint a signed document belongs to.
+ *
+ * - `<RFCE>` → the consumption-summary reception (`recepcionfc`).
+ * - `<ECF>` with any type other than E32 → the general reception.
+ * - `<ECF>` type E32 at or above RD$250,000 → the general reception.
+ * - `<ECF>` type E32 below RD$250,000 → rejected: DGII only accepts the
+ *   summary form for those, so the caller must run `convertECF32ToRFCE` first.
+ *
+ * The decision reads `TipoeCF` and `MontoTotal` from the signed document, so it
+ * cannot drift from what is actually being transmitted.
+ */
+declare const resolveReceptionRoute: (signedXml: string) => Result<ReceptionRoute, DgiiError>;
+
 /** First 6 chars of the `<SignatureValue>` (DGII security code). */
 declare const getCodeSixDigitfromSignature: (signedXml: string) => Result<string, DgiiError>;
 /** QR URL for a factura de consumo (FC). */
@@ -387,6 +445,13 @@ interface EcfOptions {
     timeoutMs?: number;
     /** Injectable fetch (useful for tests). */
     fetchImpl?: typeof fetch;
+    /**
+     * Refresh the token when its remaining lifetime falls below this window.
+     * Defaults to 5 minutes.
+     */
+    tokenRefreshSkewMs?: number;
+    /** Injectable clock (epoch milliseconds); useful for tests. */
+    now?: () => number;
 }
 /**
  * DGII e-CF client. Every method returns a `Result` — no thrown domain errors.
@@ -397,6 +462,10 @@ declare class ECF {
     private readonly idempotency;
     private readonly credentials;
     private readonly inFlight;
+    private readonly tokenRefreshSkewMs;
+    private readonly now;
+    private tokenExpiresAt;
+    private refreshPromise;
     constructor(credentials: P12ReaderData, environment?: Environment, options?: EcfOptions);
     private buildIdempotencyKey;
     /**
@@ -408,6 +477,17 @@ declare class ECF {
      */
     private submitIdempotent;
     private singleFlight;
+    /**
+     * Refresh the token when it is missing or about to expire.
+     *
+     * A pre-supplied `token` has no known expiry, so it is never refreshed
+     * proactively — only a 401 triggers a re-authentication for it.
+     */
+    private ensureToken;
+    /** Authenticate, coalescing concurrent refreshes into a single round-trip. */
+    private refreshToken;
+    /** Drop the rejected token and authenticate once. Returns `true` on success. */
+    private reauthenticate;
     /** Authenticate against DGII (or a buyer host) and store the bearer token. */
     authenticate(buyerHost?: string): Promise<Result<AuthToken, DgiiError>>;
     private getSeed;
@@ -419,6 +499,15 @@ declare class ECF {
     sendElectronicDocument(signedXml: string, fileName: string, buyerHost?: string): Promise<Result<InvoiceResponse, DgiiError>>;
     /** Submit a signed summary invoice (RFCE). Idempotent like submissions. */
     sendSummary(signedXml: string, fileName: string): Promise<Result<InvoiceSummaryResponse, DgiiError>>;
+    /**
+     * Submit a signed document to the endpoint its own content belongs to.
+     *
+     * Reads the root element, `TipoeCF` and `MontoTotal` from the signed XML and
+     * dispatches to {@link sendSummary} for an RFCE or to
+     * {@link sendElectronicDocument} for an ECF. An E32 below RD$250,000 is
+     * rejected because DGII only accepts the summary form for those.
+     */
+    sendDocument(signedXml: string, fileName: string, buyerHost?: string): Promise<Result<InvoiceResponse | InvoiceSummaryResponse, DgiiError>>;
     statusTrackId(trackId: string): Promise<Result<TrackingStatusResponse, DgiiError>>;
     inquiryStatus(rncEmisor: string, ncfElectronico: string, rncComprador?: string, codigoSeguridad?: string): Promise<Result<InquiryStatusResponse, DgiiError>>;
     trackStatuses(rncEmisor: string, encf: string): Promise<Result<SummaryTrackingStatusResponse[], DgiiError>>;
@@ -438,4 +527,4 @@ declare class ECF {
     voidENCF(signedXml: string, fileName: string): Promise<Result<VoidNCFResponse, DgiiError>>;
 }
 
-export { type AuthToken, BaseUrl, type BaseUrlKey, type CertificateInfo, type CommercialApprovalResponse, type DgiiDocumentType, DgiiError, type DgiiErrorCode, type DgiiErrorContext, type DgiiErrorOptions, type DgiiResult, ECF, type EcfOptions, Endpoint, Environment, HttpClient, type HttpClientOptions, type IdempotencyStore, InMemoryIdempotencyStore, type InMemoryIdempotencyStoreOptions, type InquiryInvoiceSummary, type InquiryStatus, type InquiryStatusCode, type InquiryStatusResponse, type InvoiceResponse, type InvoiceSummaryResponse, type Mensaje, P12Reader, type P12ReaderData, type RequestOptions, type ResilienceOptions, type ResiliencePolicies, SenderReceiverEndpoint, type ServiceDirectoryResponse, Signature, type SummaryTrackingStatusResponse, type TrackStatusCode, TrackStatusEnum, type TrackingStatusResponse, Transformer, type VoidNCFResponse, type XmlCertificateValidation, buildSenderReceiverUrl, buildUrl, convertECF32ToRFCE, createResiliencePolicies, defaultResilienceOptions, extractDgiiErrorMessage, generateEcfQRCodeURL, generateFcQRCodeURL, getCodeSixDigitfromSignature, getCurrentFormattedDate, getCurrentFormattedDateTime, getXmlFromBodyResponse, isRetryableError, isRetryableStatus, roundHalfUpToCents, toDgiiError, validateXMLCertificate };
+export { type AuthToken, BaseUrl, type BaseUrlKey, CONSUMPTION_SUMMARY_THRESHOLD, type CertificateInfo, type CommercialApprovalResponse, type DgiiDocumentType, DgiiError, type DgiiErrorCode, type DgiiErrorContext, type DgiiErrorOptions, type DgiiResult, ECF, ECF_TYPE_CODES, type EcfOptions, type EcfTypeCode, Endpoint, Environment, type GeneralReceptionRoute, HttpClient, type HttpClientOptions, type IdempotencyStore, InMemoryIdempotencyStore, type InMemoryIdempotencyStoreOptions, type InquiryInvoiceSummary, type InquiryStatus, type InquiryStatusCode, type InquiryStatusResponse, type InvoiceResponse, type InvoiceSummaryResponse, type Mensaje, P12Reader, type P12ReaderData, type ReceptionRoute, type RequestOptions, type ResilienceOptions, type ResiliencePolicies, SenderReceiverEndpoint, type ServiceDirectoryResponse, Signature, type SummaryReceptionRoute, type SummaryTrackingStatusResponse, type TrackStatusCode, TrackStatusEnum, type TrackingStatusResponse, Transformer, type VoidNCFResponse, type XmlCertificateValidation, buildSenderReceiverUrl, buildUrl, compareDecimal, convertECF32ToRFCE, createResiliencePolicies, defaultResilienceOptions, extractDgiiErrorMessage, generateEcfQRCodeURL, generateFcQRCodeURL, getCodeSixDigitfromSignature, getCurrentFormattedDate, getCurrentFormattedDateTime, getXmlFromBodyResponse, isEcfTypeCode, isRetryableError, isRetryableStatus, resolveReceptionRoute, roundHalfUpToCents, toDgiiError, validateXMLCertificate };