@lapyme/arca 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lapyme
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,178 @@
+# arca.ts
+
+`@lapyme/arca` is a Node.js client for ARCA web services. It currently covers WSAA authentication plus the first production-oriented service modules we use most often: `wsfe`, `wsmtxca`, and padron lookups.
+
+The package is ESM-first, supports Node.js `>=20`, and defaults to a safe configuration for open-source use:
+
+- WSAA credentials stay in memory by default.
+- Disk-backed WSAA caching is opt-in and requires an explicit directory.
+- The documented public surface is intentionally narrow.
+
+## Install
+
+```bash
+pnpm add @lapyme/arca
+```
+
+## Quick Start
+
+```ts
+import {
+  createArcaClient,
+  createArcaClientConfigFromEnv,
+} from "@lapyme/arca";
+
+const client = createArcaClient(
+  createArcaClientConfigFromEnv({
+    defaultEnvironment: "test",
+  })
+);
+
+const nextVoucher = await client.wsfe.getLastVoucher({
+  salesPoint: 1,
+  voucherType: 6,
+});
+
+console.log(nextVoucher);
+```
+
+Expected environment variables:
+
+- `ARCA_TAX_ID`
+- `ARCA_CERTIFICATE_PEM`
+- `ARCA_PRIVATE_KEY_PEM`
+- `ARCA_ENVIRONMENT` with `test` or `production`
+
+The helper defaults `ARCA_ENVIRONMENT` to `test` when it is omitted.
+
+## Configuration
+
+You can pass configuration directly instead of loading it from environment variables:
+
+```ts
+import { createArcaClient } from "@lapyme/arca";
+
+const client = createArcaClient({
+  taxId: "20123456789",
+  certificatePem: process.env.ARCA_CERTIFICATE_PEM!,
+  privateKeyPem: process.env.ARCA_PRIVATE_KEY_PEM!,
+  environment: "test",
+});
+```
+
+### Opt-in disk cache for WSAA credentials
+
+By default, WSAA login tickets are cached in memory only. To persist them across process restarts, enable disk cache explicitly:
+
+```ts
+import { createArcaClient } from "@lapyme/arca";
+
+const client = createArcaClient({
+  taxId: "20123456789",
+  certificatePem: process.env.ARCA_CERTIFICATE_PEM!,
+  privateKeyPem: process.env.ARCA_PRIVATE_KEY_PEM!,
+  environment: "production",
+  wsaa: {
+    cache: {
+      mode: "disk",
+      directory: ".arca-wsaa-cache",
+    },
+  },
+});
+```
+
+Environment-based configuration also supports:
+
+- `ARCA_WSAA_CACHE_MODE` with `memory` or `disk`
+- `ARCA_WSAA_CACHE_DIRECTORY` when `ARCA_WSAA_CACHE_MODE=disk`
+
+## Supported Modules
+
+### `client.wsfe`
+
+WSFE electronic invoicing. All inputs and outputs use JS-convention names; the library maps them to AFIP's SOAP schema internally.
+
+- `createNextVoucher({ data })` — Authorizes a new voucher. Takes a typed `WsfeVoucherInput` and returns `WsfeAuthorizationResult` with `cae`, `caeExpiry`, `voucherNumber`, and `raw`.
+- `getLastVoucher({ salesPoint, voucherType })` — Returns the next available voucher number.
+- `getSalesPoints({})` — Lists configured points of sale as `WsfeSalesPoint[]`.
+- `getVoucherInfo({ number, salesPoint, voucherType })` — Retrieves voucher details as `WsfeVoucherInfo | null`.
+
+```ts
+const result = await client.wsfe.createNextVoucher({
+  data: {
+    salesPoint: 1,
+    voucherType: 6,
+    concept: 1,
+    documentType: 80,
+    documentNumber: 30717329654,
+    voucherDate: "20260501",
+    totalAmount: 121,
+    nonTaxableAmount: 0,
+    netAmount: 100,
+    exemptAmount: 0,
+    taxAmount: 0,
+    vatAmount: 21,
+    currencyId: "PES",
+    exchangeRate: 1,
+    vatRates: [{ id: 5, baseAmount: 100, amount: 21 }],
+  },
+});
+
+console.log(result.cae, result.caeExpiry, result.voucherNumber);
+```
+
+### `client.wsmtxca`
+
+WSMTXCA electronic invoicing (Factura de Crédito Electrónica).
+
+- `authorizeVoucher({ data })` — Returns `WsmtxcaAuthorizationResult`.
+- `getLastAuthorizedVoucher({ voucherType, salesPoint })` — Returns `WsmtxcaLastAuthorizedVoucherResult`.
+- `getVoucher({ voucherType, salesPoint, voucherNumber })` — Returns `WsmtxcaVoucherLookupResult`.
+
+### `client.padron`
+
+Padron taxpayer registry lookups.
+
+- `getTaxpayerDetails(taxId)` — Returns `PadronTaxpayerResult | null` with `taxId`, `name`, `personType`, and `raw`.
+- `getTaxIdByDocument(documentNumber)` — Returns `PadronTaxIdLookupResult | null` with `taxIds` and `raw`.
+
+You can also import the service factories directly from documented subpaths:
+
+```ts
+import { createWsfeService } from "@lapyme/arca/wsfe";
+import { ArcaServiceError } from "@lapyme/arca/errors";
+import type { WsfeVoucherInput } from "@lapyme/arca/wsfe";
+```
+
+## Public API
+
+Documented, semver-governed entrypoints:
+
+- `@lapyme/arca`
+- `@lapyme/arca/wsfe`
+- `@lapyme/arca/wsmtxca`
+- `@lapyme/arca/padron`
+- `@lapyme/arca/errors`
+- `@lapyme/arca/types`
+
+Low-level SOAP, HTTP, and WSAA internals are intentionally not part of the public contract.
+
+## Development
+
+```bash
+pnpm install
+pnpm typecheck
+pnpm test
+pnpm test:coverage
+pnpm pack:check
+```
+
+## Security Notes
+
+- Treat your certificate and private key as secrets.
+- Default in-memory WSAA caching avoids silent disk writes.
+- If you enable disk cache, point it at a directory with appropriate filesystem permissions for your runtime.
+
+## License
+
+MIT

package/dist/errors.d.ts

@@ -0,0 +1,43 @@
+/** Base error class for all ARCA-related errors. */
+declare class ArcaError extends Error {
+    readonly code: string;
+    readonly name: string;
+    constructor(message: string, code?: string, options?: ErrorOptions);
+}
+/** Thrown when the ARCA client configuration is missing or invalid. */
+declare class ArcaConfigurationError extends ArcaError {
+    readonly name: string;
+    constructor(message: string, options?: ErrorOptions);
+}
+/** Thrown when an HTTP request to an ARCA endpoint fails at the transport level. */
+declare class ArcaTransportError extends ArcaError {
+    readonly name: string;
+    readonly statusCode?: number;
+    readonly responseBody?: string;
+    constructor(message: string, options?: ErrorOptions & {
+        statusCode?: number;
+        responseBody?: string;
+    });
+}
+/** Thrown when the SOAP response contains a Fault element. */
+declare class ArcaSoapFaultError extends ArcaError {
+    readonly name: string;
+    readonly faultCode?: string;
+    readonly detail?: unknown;
+    constructor(message: string, options?: ErrorOptions & {
+        faultCode?: string;
+        detail?: unknown;
+    });
+}
+/** Thrown when an ARCA service (WSFE, WSMTXCA, Padron) returns a domain-level error. */
+declare class ArcaServiceError extends ArcaError {
+    readonly name: string;
+    readonly serviceCode?: string | number;
+    readonly detail?: unknown;
+    constructor(message: string, options?: ErrorOptions & {
+        serviceCode?: string | number;
+        detail?: unknown;
+    });
+}
+
+export { ArcaConfigurationError, ArcaError, ArcaServiceError, ArcaSoapFaultError, ArcaTransportError };

package/dist/errors.js

@@ -0,0 +1,53 @@
+// src/errors.ts
+var ArcaError = class extends Error {
+  code;
+  name = "ArcaError";
+  constructor(message, code = "ARCA_ERROR", options) {
+    super(message, options);
+    this.code = code;
+  }
+};
+var ArcaConfigurationError = class extends ArcaError {
+  name = "ArcaConfigurationError";
+  constructor(message, options) {
+    super(message, "ARCA_CONFIGURATION_ERROR", options);
+  }
+};
+var ArcaTransportError = class extends ArcaError {
+  name = "ArcaTransportError";
+  statusCode;
+  responseBody;
+  constructor(message, options) {
+    super(message, "ARCA_TRANSPORT_ERROR", options);
+    this.statusCode = options?.statusCode;
+    this.responseBody = options?.responseBody;
+  }
+};
+var ArcaSoapFaultError = class extends ArcaError {
+  name = "ArcaSoapFaultError";
+  faultCode;
+  detail;
+  constructor(message, options) {
+    super(message, "ARCA_SOAP_FAULT", options);
+    this.faultCode = options?.faultCode;
+    this.detail = options?.detail;
+  }
+};
+var ArcaServiceError = class extends ArcaError {
+  name = "ArcaServiceError";
+  serviceCode;
+  detail;
+  constructor(message, options) {
+    super(message, "ARCA_SERVICE_ERROR", options);
+    this.serviceCode = options?.serviceCode;
+    this.detail = options?.detail;
+  }
+};
+export {
+  ArcaConfigurationError,
+  ArcaError,
+  ArcaServiceError,
+  ArcaSoapFaultError,
+  ArcaTransportError
+};
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts"],"sourcesContent":["/** 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\nclass ArcaNotImplementedError extends ArcaError {\n  override readonly name: string = \"ArcaNotImplementedError\";\n\n  constructor(message: string, options?: ErrorOptions) {\n    super(message, \"ARCA_NOT_IMPLEMENTED\", options);\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 responseBody?: string;\n\n  constructor(\n    message: string,\n    options?: ErrorOptions & {\n      statusCode?: number;\n      responseBody?: string;\n    }\n  ) {\n    super(message, \"ARCA_TRANSPORT_ERROR\", options);\n    this.statusCode = options?.statusCode;\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 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 detail?: unknown;\n\n  constructor(\n    message: string,\n    options?: ErrorOptions & {\n      serviceCode?: string | number;\n      detail?: unknown;\n    }\n  ) {\n    super(message, \"ARCA_SERVICE_ERROR\", options);\n    this.serviceCode = options?.serviceCode;\n    this.detail = options?.detail;\n  }\n}\n"],"mappings":";AACO,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;AAWO,IAAM,qBAAN,cAAiC,UAAU;AAAA,EAC9B,OAAe;AAAA,EACxB;AAAA,EACA;AAAA,EAET,YACE,SACA,SAIA;AACA,UAAM,SAAS,wBAAwB,OAAO;AAC9C,SAAK,aAAa,SAAS;AAC3B,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,mBAAN,cAA+B,UAAU;AAAA,EAC5B,OAAe;AAAA,EACxB;AAAA,EACA;AAAA,EAET,YACE,SACA,SAIA;AACA,UAAM,SAAS,sBAAsB,OAAO;AAC5C,SAAK,cAAc,SAAS;AAC5B,SAAK,SAAS,SAAS;AAAA,EACzB;AACF;","names":[]}

package/dist/index-vWZOjFDO.d.ts

@@ -0,0 +1,11 @@
+import { j as ArcaSoapExecutionOptions, k as ArcaSoapResponse, i as ArcaWsaaServiceId, c as ArcaAuthOptions, b as ArcaAuthCredentials } from './types-DWsYue4B.js';
+
+type SoapTransport = {
+    execute<TBody, TResult>(request: ArcaSoapExecutionOptions<TBody>): Promise<ArcaSoapResponse<TResult>>;
+};
+
+type WsaaAuthModule = {
+    login(service: ArcaWsaaServiceId, options?: ArcaAuthOptions): Promise<ArcaAuthCredentials>;
+};
+
+export type { SoapTransport as S, WsaaAuthModule as W };

package/dist/index.d.ts

@@ -0,0 +1,62 @@
+import { A as ArcaClientConfig, a as ArcaEnvironment } from './types-DWsYue4B.js';
+export { b as ArcaAuthCredentials, c as ArcaAuthOptions, d as ArcaPadronServiceName, e as ArcaRepresentedTaxId, f as ArcaServiceName, g as ArcaServiceTarget, h as ArcaWsaaCacheConfig, i as ArcaWsaaServiceId } from './types-DWsYue4B.js';
+import { PadronService } from './padron.js';
+export { CreatePadronServiceOptions, PadronTaxIdLookupResult, PadronTaxpayerResult, createPadronService } from './padron.js';
+import { WsfeService } from './wsfe.js';
+export { CreateWsfeServiceOptions, WsfeAssociatedVoucher, WsfeAuthorizationResult, WsfeBuyer, WsfeOptionalField, WsfeSalesPoint, WsfeTax, WsfeVatRate, WsfeVoucherInfo, WsfeVoucherInput, createWsfeService } from './wsfe.js';
+import { WsmtxcaService } from './wsmtxca.js';
+export { CreateWsmtxcaServiceOptions, WsmtxcaAuthorizationResult, WsmtxcaLastAuthorizedVoucherResult, WsmtxcaVoucherLookupResult, createWsmtxcaService } from './wsmtxca.js';
+export { ArcaConfigurationError, ArcaError, ArcaServiceError, ArcaSoapFaultError, ArcaTransportError } from './errors.js';
+import './index-vWZOjFDO.js';
+
+/** Fully wired ARCA client with access to all service modules. */
+type ArcaClient = {
+    config: ArcaClientConfig;
+    wsfe: WsfeService;
+    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.
+ *
+ * @throws {ArcaConfigurationError} When the config is missing or invalid.
+ */
+declare function createArcaClient(config: ArcaClientConfig): ArcaClient;
+
+/** Valid ARCA environment names. */
+declare const ARCA_ENVIRONMENTS: readonly ["production", "test"];
+/** Default environment variable names read by {@link createArcaClientConfigFromEnv}. */
+declare const ARCA_ENV_VARIABLES: {
+    readonly taxId: "ARCA_TAX_ID";
+    readonly certificatePem: "ARCA_CERTIFICATE_PEM";
+    readonly privateKeyPem: "ARCA_PRIVATE_KEY_PEM";
+    readonly environment: "ARCA_ENVIRONMENT";
+    readonly wsaaCacheMode: "ARCA_WSAA_CACHE_MODE";
+    readonly wsaaCacheDirectory: "ARCA_WSAA_CACHE_DIRECTORY";
+};
+type ArcaClientConfigEnvironment = Record<string, string | undefined>;
+/** Options for {@link createArcaClientConfigFromEnv}. */
+type CreateArcaClientConfigFromEnvOptions = {
+    env?: ArcaClientConfigEnvironment;
+    defaultEnvironment?: ArcaEnvironment;
+    variableNames?: Partial<typeof ARCA_ENV_VARIABLES>;
+};
+/** Returns `"production"` or `"test"` based on the boolean flag. */
+declare function resolveArcaEnvironment(production: boolean): ArcaEnvironment;
+/**
+ * Builds an {@link ArcaClientConfig} from environment variables.
+ * Reads `process.env` by default; override with `options.env`.
+ *
+ * @throws {ArcaConfigurationError} When required variables are missing or invalid.
+ */
+declare function createArcaClientConfigFromEnv(options?: CreateArcaClientConfigFromEnvOptions): ArcaClientConfig;
+/**
+ * Validates an {@link ArcaClientConfig} and throws if any field is invalid.
+ *
+ * @throws {ArcaConfigurationError} With a list of invalid field names.
+ */
+declare function assertArcaClientConfig(config: ArcaClientConfig): void;
+
+export { ARCA_ENVIRONMENTS, ARCA_ENV_VARIABLES, type ArcaClient, ArcaClientConfig, ArcaEnvironment, type CreateArcaClientConfigFromEnvOptions, PadronService, WsfeService, WsmtxcaService, assertArcaClientConfig, createArcaClient, createArcaClientConfigFromEnv, resolveArcaEnvironment };