alegra-api-client 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gary Dormoi
+
+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,185 @@
+# alegra-api-client
+
+[![CI](https://github.com/garydormoi/alegra-api-client/actions/workflows/ci.yml/badge.svg)](https://github.com/garydormoi/alegra-api-client/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+
+Cliente ligero y **tipado** (TypeScript) para la [API de Alegra](https://developer.alegra.com/).
+Cubre lo esencial de la capa de integración: **autenticación**, **paginación** y
+**manejo de rate limits** con reintentos, sobre `contactos`, `ítems` y `facturas`.
+
+> Proyecto **no oficial** y sin afiliación con Alegra. Alegra® es marca de sus
+> respectivos dueños. Documentación en español porque hay poca disponible.
+
+## Características
+
+- Autenticación HTTP Basic (`correo:token`), portable (Node, Deno, edge).
+- Paginación por `start`/`limit` (máx. 30 por página) con generador asíncrono
+  para no cargar todo en memoria.
+- Manejo de **rate limit (HTTP 429)** respetando `Retry-After`, con reintentos
+  y retroceso exponencial con jitter.
+- Reintentos también ante errores de red y `5xx`; los `4xx` no se reintentan.
+- Throttle preventivo opcional entre solicitudes.
+- Timeout por solicitud con `AbortController`.
+- Cero dependencias en tiempo de ejecución (usa `fetch` nativo de Node ≥ 18).
+
+## Instalación
+
+```bash
+npm install alegra-api-client
+```
+
+Requiere Node.js 18 o superior (por `fetch` nativo).
+
+## Autenticación
+
+La API de Alegra usa autenticación **HTTP Basic** con tu **correo** y un **token**
+de API (no tu contraseña). El token se genera en Alegra, en la sección de
+integraciones / API de tu cuenta.
+
+Guarda las credenciales en variables de entorno, nunca en el código:
+
+```bash
+cp .env.example .env
+# edita .env con tus valores reales
+```
+
+## Uso rápido
+
+```ts
+import { Alegra } from "alegra-api-client";
+
+const alegra = new Alegra({
+  email: process.env.ALEGRA_EMAIL!,
+  token: process.env.ALEGRA_TOKEN!,
+});
+
+// Una página (máx. 30)
+const clientes = await alegra.contactos.listar({ type: "client", limit: 30 });
+
+// Descargar todo (paginando internamente)
+const todos = await alegra.contactos.listarTodos({ type: "client" });
+
+// Un recurso por id
+const factura = await alegra.facturas.obtener("123");
+```
+
+## Paginación
+
+La API devuelve como máximo 30 registros por página. Usa el generador para
+procesar página por página sin agotar memoria:
+
+```ts
+for await (const pagina of alegra.facturas.paginar({
+  date_afterOrNow: "2026-01-01",
+  date_beforeOrNow: "2026-01-31",
+})) {
+  for (const factura of pagina) {
+    // procesar
+  }
+}
+```
+
+O junta todo de una vez con `listarTodas` / `listarTodos` / `collectAll`.
+
+## Manejo de rate limits y reintentos
+
+La API de Alegra permite **150 solicitudes por minuto por usuario** (≈ 2.5/seg).
+Al excederlo responde **HTTP 429** e informa el estado en cabeceras
+`X-Rate-Limit-Limit`, `X-Rate-Limit-Remaining` y `X-Rate-Limit-Reset` (segundos
+que faltan para reiniciar la ventana). Alegra **no** envía `Retry-After`.
+
+El cliente reintenta automáticamente ante `429` y `5xx`. Ante `429` espera lo que
+indique `X-Rate-Limit-Reset` (o `Retry-After` si estuviera presente) y, si no hay
+ninguno, aplica retroceso exponencial con jitter.
+
+```ts
+const alegra = new Alegra({
+  email,
+  token,
+  minRequestIntervalMs: 400, // ≈150/min: espaciado preventivo para no llegar al límite
+  maxRetries: 3,             // reintentos ante 429 / 5xx
+  retryBaseMs: 500,          // backoff base
+  timeoutMs: 30000,          // timeout por solicitud
+});
+```
+
+Si se agotan los reintentos ante `429`, se lanza `AlegraRateLimitError` (con
+`retryAfterSeconds` cuando la respuesta lo permite calcular).
+
+## Manejo de errores
+
+```ts
+import { AlegraApiError, AlegraRateLimitError } from "alegra-api-client";
+
+try {
+  await alegra.facturas.obtener("no-existe");
+} catch (err) {
+  if (err instanceof AlegraRateLimitError) {
+    // esperar y reintentar más tarde
+  } else if (err instanceof AlegraApiError) {
+    console.error(err.status, err.endpoint, err.body);
+  }
+}
+```
+
+## Recursos disponibles
+
+| Recurso     | Métodos                                             |
+| ----------- | --------------------------------------------------- |
+| `contactos` | `listar`, `obtener`, `paginar`, `listarTodos`       |
+| `items`     | `listar`, `obtener`, `paginar`, `listarTodos`       |
+| `facturas`  | `listar`, `obtener`, `paginar`, `listarTodas`       |
+
+Para endpoints no cubiertos por los recursos, usa el cliente directo:
+
+```ts
+const data = await alegra.client.request<MiTipo>("otro-endpoint", {
+  query: { limit: 30 },
+});
+```
+
+## Referencia rápida de la API de Alegra
+
+Resumen de los hechos de la API en que se basa este cliente (fuente:
+documentación oficial de Alegra para desarrolladores).
+
+| Tema | Detalle |
+| --- | --- |
+| URL base | `https://api.alegra.com/api/v1` |
+| Autenticación | HTTP **Basic**: `Authorization: Basic base64(correo:token)` |
+| Token | Alegra → Configuración → *API - Integraciones con otros sistemas* |
+| Error de autenticación | HTTP **401** |
+| Límite de uso | **150 solicitudes/minuto por usuario** |
+| Límite excedido | HTTP **429** + cabeceras `X-Rate-Limit-Limit` / `X-Rate-Limit-Remaining` / `X-Rate-Limit-Reset` |
+| Paginación | Parámetros `start` (offset) y `limit`; **máximo 30** por página |
+
+Referencias:
+[Autenticación](https://developer.alegra.com/reference/autenticaci%C3%B3n) ·
+[Límite de request](https://developer.alegra.com/reference/l%C3%ADmite-de-request) ·
+[Documentación general](https://developer.alegra.com/docs)
+
+> Este resumen existe porque la documentación en español de la API de Alegra es
+> escasa. Si algo cambia en la API oficial, esta tabla debe actualizarse.
+
+## Desarrollo
+
+```bash
+npm install
+npm run build      # compila a dist/
+npm test           # pruebas con vitest (fetch simulado, datos ficticios)
+npm run lint:types # verificación de tipos sin emitir
+```
+
+Los ejemplos en `examples/` usan datos **ficticios** y credenciales por variables
+de entorno.
+
+## Contribuir
+
+Los issues y PRs son bienvenidos. Al reportar un problema, incluye el endpoint,
+los parámetros usados (sin credenciales) y el comportamiento esperado.
+
+## Licencia
+
+[MIT](./LICENSE)
+
+## Changelog
+- 0.1.0 - primera version publica

package/dist/client.d.ts

@@ -0,0 +1,86 @@
+/** Opciones de construcción del cliente. */
+export interface AlegraClientOptions {
+    /** Correo de la cuenta de Alegra (usuario en la autenticación Basic). */
+    email: string;
+    /** Token de la API de Alegra. */
+    token: string;
+    /** URL base de la API. Por defecto: https://api.alegra.com/api/v1 */
+    baseUrl?: string;
+    /**
+     * Milisegundos mínimos entre solicitudes (throttle preventivo del lado cliente).
+     * Útil para no acercarse al límite de la API. Por defecto: 0 (sin throttle).
+     */
+    minRequestIntervalMs?: number;
+    /** Número máximo de reintentos ante 429 y errores 5xx. Por defecto: 3. */
+    maxRetries?: number;
+    /** Backoff base (ms) para el retroceso exponencial. Por defecto: 500. */
+    retryBaseMs?: number;
+    /** Tiempo máximo por solicitud (ms) antes de abortar. Por defecto: 30000. */
+    timeoutMs?: number;
+    /** Implementación de fetch a usar (inyectable para pruebas). Por defecto: globalThis.fetch. */
+    fetchImpl?: typeof fetch;
+    /** Cadena User-Agent enviada en cada solicitud. */
+    userAgent?: string;
+}
+/** Opciones por solicitud individual. */
+export interface RequestOptions {
+    method?: string;
+    /** Parámetros de query. Los `undefined` se omiten. */
+    query?: Record<string, string | number | boolean | undefined>;
+    /** Cuerpo a serializar como JSON (para POST/PUT). */
+    body?: unknown;
+    /** Señal externa de cancelación. */
+    signal?: AbortSignal;
+}
+/**
+ * Cliente HTTP para la API de Alegra.
+ *
+ * Responsabilidades:
+ *  - Autenticación HTTP Basic (`email:token`).
+ *  - Serialización de query y cuerpo JSON.
+ *  - Manejo de rate limit (HTTP 429) respetando `Retry-After`.
+ *  - Reintentos con retroceso exponencial ante 429 y 5xx.
+ *  - Throttle preventivo opcional entre solicitudes.
+ *  - Timeout por solicitud.
+ *
+ * @example
+ * const client = new AlegraClient({ email: "demo@ejemplo.com", token: "TU_TOKEN" });
+ * const contactos = await client.request<Contacto[]>("contacts", { query: { limit: 30 } });
+ */
+export declare class AlegraClient {
+    private readonly baseUrl;
+    private readonly authHeader;
+    private readonly minRequestIntervalMs;
+    private readonly maxRetries;
+    private readonly retryBaseMs;
+    private readonly timeoutMs;
+    private readonly fetchImpl;
+    private readonly userAgent;
+    private lastRequestAt;
+    constructor(options: AlegraClientOptions);
+    /** Construye la URL completa a partir del endpoint relativo y la query. */
+    private buildUrl;
+    /** Lee `Retry-After` (segundos o fecha HTTP) y lo convierte a milisegundos. */
+    private parseRetryAfter;
+    /**
+     * Lee `X-Rate-Limit-Reset` (segundos que faltan para reiniciar la ventana) y lo
+     * convierte a milisegundos. Alegra devuelve este header en cada respuesta y NO
+     * envía `Retry-After`, por lo que es la señal de espera fiable ante un 429.
+     * Ref.: https://developer.alegra.com/reference/límite-de-request
+     */
+    private parseResetSeconds;
+    /**
+     * Realiza una solicitud a la API y devuelve el JSON tipado.
+     *
+     * @typeParam T - Forma esperada de la respuesta.
+     * @throws {AlegraRateLimitError} si se agotan los reintentos ante 429.
+     * @throws {AlegraApiError} ante cualquier otra respuesta no 2xx.
+     */
+    request<T>(endpoint: string, options?: RequestOptions): Promise<T>;
+    /** Espera lo necesario para respetar `minRequestIntervalMs`. */
+    private throttle;
+    /** Backoff exponencial con jitter. */
+    private backoffMs;
+    /** Intenta parsear JSON; si no es JSON, devuelve el texto. */
+    private parseBody;
+}

package/dist/client.js

@@ -0,0 +1,195 @@
+import { AlegraApiError, AlegraRateLimitError } from "./errors.js";
+const DEFAULT_BASE_URL = "https://api.alegra.com/api/v1";
+/** Codifica `usuario:token` en base64, de forma portable (Node, Deno, edge). */
+function toBase64(input) {
+    if (typeof btoa === "function")
+        return btoa(input);
+    // eslint-disable-next-line no-undef
+    return Buffer.from(input, "utf-8").toString("base64");
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+ * Cliente HTTP para la API de Alegra.
+ *
+ * Responsabilidades:
+ *  - Autenticación HTTP Basic (`email:token`).
+ *  - Serialización de query y cuerpo JSON.
+ *  - Manejo de rate limit (HTTP 429) respetando `Retry-After`.
+ *  - Reintentos con retroceso exponencial ante 429 y 5xx.
+ *  - Throttle preventivo opcional entre solicitudes.
+ *  - Timeout por solicitud.
+ *
+ * @example
+ * const client = new AlegraClient({ email: "demo@ejemplo.com", token: "TU_TOKEN" });
+ * const contactos = await client.request<Contacto[]>("contacts", { query: { limit: 30 } });
+ */
+export class AlegraClient {
+    baseUrl;
+    authHeader;
+    minRequestIntervalMs;
+    maxRetries;
+    retryBaseMs;
+    timeoutMs;
+    fetchImpl;
+    userAgent;
+    lastRequestAt = 0;
+    constructor(options) {
+        if (!options.email || !options.token) {
+            throw new Error("AlegraClient requiere `email` y `token`.");
+        }
+        this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+        this.authHeader = `Basic ${toBase64(`${options.email}:${options.token}`)}`;
+        this.minRequestIntervalMs = options.minRequestIntervalMs ?? 0;
+        this.maxRetries = options.maxRetries ?? 3;
+        this.retryBaseMs = options.retryBaseMs ?? 500;
+        this.timeoutMs = options.timeoutMs ?? 30_000;
+        const injected = options.fetchImpl ?? globalThis.fetch;
+        if (typeof injected !== "function") {
+            throw new Error("No se encontró `fetch`. Usa Node >=18, o pasa `fetchImpl` en las opciones.");
+        }
+        this.fetchImpl = injected;
+        this.userAgent = options.userAgent ?? "alegra-api-client";
+    }
+    /** Construye la URL completa a partir del endpoint relativo y la query. */
+    buildUrl(endpoint, query) {
+        const path = endpoint.replace(/^\/+/, "");
+        const url = new URL(`${this.baseUrl}/${path}`);
+        if (query) {
+            for (const [key, value] of Object.entries(query)) {
+                if (value !== undefined)
+                    url.searchParams.set(key, String(value));
+            }
+        }
+        return url.toString();
+    }
+    /** Lee `Retry-After` (segundos o fecha HTTP) y lo convierte a milisegundos. */
+    parseRetryAfter(header) {
+        if (!header)
+            return undefined;
+        const asSeconds = Number(header);
+        if (!Number.isNaN(asSeconds))
+            return Math.max(0, asSeconds * 1000);
+        const asDate = Date.parse(header);
+        if (!Number.isNaN(asDate))
+            return Math.max(0, asDate - Date.now());
+        return undefined;
+    }
+    /**
+     * Lee `X-Rate-Limit-Reset` (segundos que faltan para reiniciar la ventana) y lo
+     * convierte a milisegundos. Alegra devuelve este header en cada respuesta y NO
+     * envía `Retry-After`, por lo que es la señal de espera fiable ante un 429.
+     * Ref.: https://developer.alegra.com/reference/límite-de-request
+     */
+    parseResetSeconds(header) {
+        if (!header)
+            return undefined;
+        const asSeconds = Number(header);
+        if (Number.isNaN(asSeconds))
+            return undefined;
+        return Math.max(0, asSeconds * 1000);
+    }
+    /**
+     * Realiza una solicitud a la API y devuelve el JSON tipado.
+     *
+     * @typeParam T - Forma esperada de la respuesta.
+     * @throws {AlegraRateLimitError} si se agotan los reintentos ante 429.
+     * @throws {AlegraApiError} ante cualquier otra respuesta no 2xx.
+     */
+    async request(endpoint, options = {}) {
+        const url = this.buildUrl(endpoint, options.query);
+        const method = options.method ?? "GET";
+        let attempt = 0;
+        // Reintentos: 429 y 5xx. 4xx (salvo 429) no se reintentan.
+        for (;;) {
+            await this.throttle();
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+            if (options.signal) {
+                options.signal.addEventListener("abort", () => controller.abort(), { once: true });
+            }
+            let response;
+            try {
+                response = await this.fetchImpl(url, {
+                    method,
+                    headers: {
+                        Accept: "application/json",
+                        Authorization: this.authHeader,
+                        "User-Agent": this.userAgent,
+                        ...(options.body !== undefined ? { "Content-Type": "application/json" } : {}),
+                    },
+                    body: options.body !== undefined ? JSON.stringify(options.body) : undefined,
+                    signal: controller.signal,
+                });
+            }
+            catch (err) {
+                clearTimeout(timeout);
+                // Errores de red / abort: reintentar con backoff si quedan intentos.
+                if (attempt < this.maxRetries) {
+                    await sleep(this.backoffMs(attempt));
+                    attempt += 1;
+                    continue;
+                }
+                throw new AlegraApiError(`Fallo de red al llamar a Alegra (${endpoint}): ${err.message}`, { status: 0, body: null, endpoint });
+            }
+            finally {
+                clearTimeout(timeout);
+            }
+            if (response.ok) {
+                return (await this.parseBody(response));
+            }
+            const body = await this.parseBody(response);
+            if (response.status === 429) {
+                // Alegra: 150 req/min por usuario. No envía Retry-After; usa X-Rate-Limit-Reset
+                // (segundos que faltan para reiniciar la ventana de 1 minuto).
+                const retryAfterMs = this.parseRetryAfter(response.headers.get("Retry-After"));
+                const resetMs = this.parseResetSeconds(response.headers.get("X-Rate-Limit-Reset"));
+                const waitMs = retryAfterMs ?? resetMs;
+                if (attempt < this.maxRetries) {
+                    await sleep(waitMs ?? this.backoffMs(attempt));
+                    attempt += 1;
+                    continue;
+                }
+                throw new AlegraRateLimitError(`Rate limit de Alegra (429) tras ${this.maxRetries} reintentos en ${endpoint}.`, {
+                    status: 429,
+                    body,
+                    endpoint,
+                    retryAfterSeconds: waitMs !== undefined ? waitMs / 1000 : undefined,
+                });
+            }
+            if (response.status >= 500 && attempt < this.maxRetries) {
+                await sleep(this.backoffMs(attempt));
+                attempt += 1;
+                continue;
+            }
+            throw new AlegraApiError(`Alegra respondió ${response.status} en ${endpoint}.`, { status: response.status, body, endpoint });
+        }
+    }
+    /** Espera lo necesario para respetar `minRequestIntervalMs`. */
+    async throttle() {
+        if (this.minRequestIntervalMs <= 0)
+            return;
+        const elapsed = Date.now() - this.lastRequestAt;
+        const wait = this.minRequestIntervalMs - elapsed;
+        if (wait > 0)
+            await sleep(wait);
+        this.lastRequestAt = Date.now();
+    }
+    /** Backoff exponencial con jitter. */
+    backoffMs(attempt) {
+        const base = this.retryBaseMs * 2 ** attempt;
+        const jitter = Math.random() * this.retryBaseMs;
+        return base + jitter;
+    }
+    /** Intenta parsear JSON; si no es JSON, devuelve el texto. */
+    async parseBody(response) {
+        const text = await response.text();
+        if (!text)
+            return null;
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return text;
+        }
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Errores del cliente de Alegra.
+ *
+ * Todas las respuestas no exitosas de la API se envuelven en {@link AlegraApiError}.
+ * Cuando el servidor responde 429 (demasiadas solicitudes) se usa la subclase
+ * {@link AlegraRateLimitError}, que expone el tiempo de espera sugerido.
+ */
+/** Error genérico de la API de Alegra (respuesta HTTP no 2xx). */
+export declare class AlegraApiError extends Error {
+    /** Código de estado HTTP devuelto por la API. */
+    readonly status: number;
+    /** Cuerpo de la respuesta, ya parseado si era JSON; si no, el texto crudo. */
+    readonly body: unknown;
+    /** Endpoint (ruta relativa) que originó el error. */
+    readonly endpoint: string;
+    constructor(message: string, params: {
+        status: number;
+        body: unknown;
+        endpoint: string;
+    });
+}
+/** Error específico de rate limit (HTTP 429). */
+export declare class AlegraRateLimitError extends AlegraApiError {
+    /** Segundos sugeridos de espera antes de reintentar (cabecera Retry-After), si vino. */
+    readonly retryAfterSeconds?: number;
+    constructor(message: string, params: {
+        status: number;
+        body: unknown;
+        endpoint: string;
+        retryAfterSeconds?: number;
+    });
+}

package/dist/errors.js

@@ -0,0 +1,33 @@
+/**
+ * Errores del cliente de Alegra.
+ *
+ * Todas las respuestas no exitosas de la API se envuelven en {@link AlegraApiError}.
+ * Cuando el servidor responde 429 (demasiadas solicitudes) se usa la subclase
+ * {@link AlegraRateLimitError}, que expone el tiempo de espera sugerido.
+ */
+/** Error genérico de la API de Alegra (respuesta HTTP no 2xx). */
+export class AlegraApiError extends Error {
+    /** Código de estado HTTP devuelto por la API. */
+    status;
+    /** Cuerpo de la respuesta, ya parseado si era JSON; si no, el texto crudo. */
+    body;
+    /** Endpoint (ruta relativa) que originó el error. */
+    endpoint;
+    constructor(message, params) {
+        super(message);
+        this.name = "AlegraApiError";
+        this.status = params.status;
+        this.body = params.body;
+        this.endpoint = params.endpoint;
+    }
+}
+/** Error específico de rate limit (HTTP 429). */
+export class AlegraRateLimitError extends AlegraApiError {
+    /** Segundos sugeridos de espera antes de reintentar (cabecera Retry-After), si vino. */
+    retryAfterSeconds;
+    constructor(message, params) {
+        super(message, params);
+        this.name = "AlegraRateLimitError";
+        this.retryAfterSeconds = params.retryAfterSeconds;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * alegra-api-client
+ *
+ * Cliente ligero y tipado para la API de Alegra.
+ * Punto de entrada: exporta el cliente HTTP, los recursos, los helpers de
+ * paginación, los tipos y los errores.
+ */
+export { AlegraClient } from "./client.js";
+export type { AlegraClientOptions, RequestOptions } from "./client.js";
+export { paginate, collectAll, MAX_LIMIT } from "./pagination.js";
+export type { PaginateOptions } from "./pagination.js";
+export { Contactos } from "./resources/contacts.js";
+export { Items } from "./resources/items.js";
+export { Facturas } from "./resources/invoices.js";
+export { AlegraApiError, AlegraRateLimitError } from "./errors.js";
+export type * from "./types.js";
+import { AlegraClient, type AlegraClientOptions } from "./client.js";
+import { Contactos } from "./resources/contacts.js";
+import { Items } from "./resources/items.js";
+import { Facturas } from "./resources/invoices.js";
+/**
+ * Fachada de conveniencia: crea el cliente y expone los recursos ya cableados.
+ *
+ * @example
+ * const alegra = new Alegra({ email: "demo@ejemplo.com", token: "TU_TOKEN" });
+ * const clientes = await alegra.contactos.listarTodos({ type: "client" });
+ * const facturas = await alegra.facturas.listar({ limit: 30 });
+ */
+export declare class Alegra {
+    /** Cliente HTTP subyacente (por si necesitas endpoints no cubiertos por los recursos). */
+    readonly client: AlegraClient;
+    readonly contactos: Contactos;
+    readonly items: Items;
+    readonly facturas: Facturas;
+    constructor(options: AlegraClientOptions);
+}

package/dist/index.js

@@ -0,0 +1,38 @@
+/**
+ * alegra-api-client
+ *
+ * Cliente ligero y tipado para la API de Alegra.
+ * Punto de entrada: exporta el cliente HTTP, los recursos, los helpers de
+ * paginación, los tipos y los errores.
+ */
+export { AlegraClient } from "./client.js";
+export { paginate, collectAll, MAX_LIMIT } from "./pagination.js";
+export { Contactos } from "./resources/contacts.js";
+export { Items } from "./resources/items.js";
+export { Facturas } from "./resources/invoices.js";
+export { AlegraApiError, AlegraRateLimitError } from "./errors.js";
+import { AlegraClient } from "./client.js";
+import { Contactos } from "./resources/contacts.js";
+import { Items } from "./resources/items.js";
+import { Facturas } from "./resources/invoices.js";
+/**
+ * Fachada de conveniencia: crea el cliente y expone los recursos ya cableados.
+ *
+ * @example
+ * const alegra = new Alegra({ email: "demo@ejemplo.com", token: "TU_TOKEN" });
+ * const clientes = await alegra.contactos.listarTodos({ type: "client" });
+ * const facturas = await alegra.facturas.listar({ limit: 30 });
+ */
+export class Alegra {
+    /** Cliente HTTP subyacente (por si necesitas endpoints no cubiertos por los recursos). */
+    client;
+    contactos;
+    items;
+    facturas;
+    constructor(options) {
+        this.client = new AlegraClient(options);
+        this.contactos = new Contactos(this.client);
+        this.items = new Items(this.client);
+        this.facturas = new Facturas(this.client);
+    }
+}

package/dist/pagination.d.ts

@@ -0,0 +1,37 @@
+import type { AlegraClient, RequestOptions } from "./client.js";
+/** Tamaño de página máximo admitido por la API de Alegra. */
+export declare const MAX_LIMIT = 30;
+/** Opciones para recorrer páginas de un recurso listable. */
+export interface PaginateOptions {
+    /** Tamaño de página (1..30). Por defecto 30. */
+    limit?: number;
+    /** Offset inicial. Por defecto 0. */
+    start?: number;
+    /** Query adicional a repetir en cada página (filtros, orden, etc.). */
+    query?: RequestOptions["query"];
+    /**
+     * Tope de páginas a recorrer (salvaguarda ante bucles). Por defecto sin tope.
+     * Útil para no agotar cuota si un filtro trae demasiados resultados.
+     */
+    maxPages?: number;
+}
+/**
+ * Itera página por página un endpoint de lista de Alegra (paginación por `start`/`limit`).
+ *
+ * La API devuelve arreglos; la paginación termina cuando una página trae menos
+ * elementos que `limit`. Se usa un generador asíncrono para no cargar todo en memoria.
+ *
+ * @typeParam T - Tipo de cada elemento.
+ * @example
+ * for await (const pagina of paginate<Factura>(client, "invoices", { limit: 30 })) {
+ *   procesar(pagina);
+ * }
+ */
+export declare function paginate<T>(client: AlegraClient, endpoint: string, options?: PaginateOptions): AsyncGenerator<T[], void, unknown>;
+/**
+ * Recorre todas las páginas y devuelve el arreglo completo.
+ *
+ * Cómodo para conjuntos moderados. Para volúmenes grandes prefiere {@link paginate}
+ * y procesa página por página.
+ */
+export declare function collectAll<T>(client: AlegraClient, endpoint: string, options?: PaginateOptions): Promise<T[]>;

package/dist/pagination.js

@@ -0,0 +1,47 @@
+/** Tamaño de página máximo admitido por la API de Alegra. */
+export const MAX_LIMIT = 30;
+/**
+ * Itera página por página un endpoint de lista de Alegra (paginación por `start`/`limit`).
+ *
+ * La API devuelve arreglos; la paginación termina cuando una página trae menos
+ * elementos que `limit`. Se usa un generador asíncrono para no cargar todo en memoria.
+ *
+ * @typeParam T - Tipo de cada elemento.
+ * @example
+ * for await (const pagina of paginate<Factura>(client, "invoices", { limit: 30 })) {
+ *   procesar(pagina);
+ * }
+ */
+export async function* paginate(client, endpoint, options = {}) {
+    const limit = Math.min(Math.max(options.limit ?? MAX_LIMIT, 1), MAX_LIMIT);
+    let start = options.start ?? 0;
+    let pages = 0;
+    for (;;) {
+        if (options.maxPages !== undefined && pages >= options.maxPages)
+            return;
+        const page = await client.request(endpoint, {
+            query: { ...options.query, start, limit },
+        });
+        const items = Array.isArray(page) ? page : [];
+        if (items.length === 0)
+            return;
+        yield items;
+        pages += 1;
+        if (items.length < limit)
+            return;
+        start += limit;
+    }
+}
+/**
+ * Recorre todas las páginas y devuelve el arreglo completo.
+ *
+ * Cómodo para conjuntos moderados. Para volúmenes grandes prefiere {@link paginate}
+ * y procesa página por página.
+ */
+export async function collectAll(client, endpoint, options = {}) {
+    const out = [];
+    for await (const page of paginate(client, endpoint, options)) {
+        out.push(...page);
+    }
+    return out;
+}

package/dist/resources/contacts.d.ts

@@ -0,0 +1,22 @@
+import type { AlegraClient } from "../client.js";
+import type { Contacto, ParametrosContactos } from "../types.js";
+/**
+ * Recurso de contactos (clientes y proveedores).
+ *
+ * @example
+ * const alegra = new AlegraClient({ email, token });
+ * const contactos = new Contactos(alegra);
+ * const primeros = await contactos.listar({ type: "client", limit: 30 });
+ */
+export declare class Contactos {
+    private readonly client;
+    constructor(client: AlegraClient);
+    /** Lista una sola página de contactos según los parámetros dados. */
+    listar(params?: ParametrosContactos): Promise<Contacto[]>;
+    /** Obtiene un contacto por su id. */
+    obtener(id: string): Promise<Contacto>;
+    /** Recorre todos los contactos página por página (generador asíncrono). */
+    paginar(params?: ParametrosContactos): AsyncGenerator<Contacto[], void, unknown>;
+    /** Descarga todos los contactos que cumplan el filtro. */
+    listarTodos(params?: ParametrosContactos): Promise<Contacto[]>;
+}

package/dist/resources/contacts.js

@@ -0,0 +1,38 @@
+import { collectAll, paginate } from "../pagination.js";
+/**
+ * Recurso de contactos (clientes y proveedores).
+ *
+ * @example
+ * const alegra = new AlegraClient({ email, token });
+ * const contactos = new Contactos(alegra);
+ * const primeros = await contactos.listar({ type: "client", limit: 30 });
+ */
+export class Contactos {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /** Lista una sola página de contactos según los parámetros dados. */
+    listar(params = {}) {
+        return this.client.request("contacts", { query: { ...params } });
+    }
+    /** Obtiene un contacto por su id. */
+    obtener(id) {
+        return this.client.request(`contacts/${encodeURIComponent(id)}`);
+    }
+    /** Recorre todos los contactos página por página (generador asíncrono). */
+    paginar(params = {}) {
+        const { start, limit, ...query } = params;
+        const opts = { start, limit, query: query };
+        return paginate(this.client, "contacts", opts);
+    }
+    /** Descarga todos los contactos que cumplan el filtro. */
+    listarTodos(params = {}) {
+        const { start, limit, ...query } = params;
+        return collectAll(this.client, "contacts", {
+            start,
+            limit,
+            query: query,
+        });
+    }
+}

package/dist/resources/invoices.d.ts

@@ -0,0 +1,28 @@
+import type { AlegraClient } from "../client.js";
+import type { Factura, ParametrosFacturas } from "../types.js";
+/**
+ * Recurso de facturas de venta.
+ *
+ * @example
+ * const facturas = new Facturas(alegra);
+ * for await (const pagina of facturas.paginar({ date_afterOrNow: "2026-01-01" })) {
+ *   // procesar cada página sin cargar todo en memoria
+ * }
+ */
+export declare class Facturas {
+    private readonly client;
+    constructor(client: AlegraClient);
+    /** Lista una sola página de facturas. */
+    listar(params?: ParametrosFacturas): Promise<Factura[]>;
+    /** Obtiene una factura por su id. */
+    obtener(id: string): Promise<Factura>;
+    /** Recorre todas las facturas página por página. */
+    paginar(params?: ParametrosFacturas): AsyncGenerator<Factura[], void, unknown>;
+    /**
+     * Descarga todas las facturas que cumplan el filtro.
+     *
+     * Nota: para rangos de fechas muy amplios conviene usar {@link paginar} y procesar
+     * por página, o acotar con `date_afterOrNow` / `date_beforeOrNow`.
+     */
+    listarTodas(params?: ParametrosFacturas): Promise<Factura[]>;
+}

package/dist/resources/invoices.js

@@ -0,0 +1,47 @@
+import { collectAll, paginate } from "../pagination.js";
+/**
+ * Recurso de facturas de venta.
+ *
+ * @example
+ * const facturas = new Facturas(alegra);
+ * for await (const pagina of facturas.paginar({ date_afterOrNow: "2026-01-01" })) {
+ *   // procesar cada página sin cargar todo en memoria
+ * }
+ */
+export class Facturas {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /** Lista una sola página de facturas. */
+    listar(params = {}) {
+        return this.client.request("invoices", { query: { ...params } });
+    }
+    /** Obtiene una factura por su id. */
+    obtener(id) {
+        return this.client.request(`invoices/${encodeURIComponent(id)}`);
+    }
+    /** Recorre todas las facturas página por página. */
+    paginar(params = {}) {
+        const { start, limit, ...query } = params;
+        return paginate(this.client, "invoices", {
+            start,
+            limit,
+            query: query,
+        });
+    }
+    /**
+     * Descarga todas las facturas que cumplan el filtro.
+     *
+     * Nota: para rangos de fechas muy amplios conviene usar {@link paginar} y procesar
+     * por página, o acotar con `date_afterOrNow` / `date_beforeOrNow`.
+     */
+    listarTodas(params = {}) {
+        const { start, limit, ...query } = params;
+        return collectAll(this.client, "invoices", {
+            start,
+            limit,
+            query: query,
+        });
+    }
+}

package/dist/resources/items.d.ts

@@ -0,0 +1,21 @@
+import type { AlegraClient } from "../client.js";
+import type { Item, ParametrosItems } from "../types.js";
+/**
+ * Recurso de ítems (productos y servicios).
+ *
+ * @example
+ * const items = new Items(alegra);
+ * const todos = await items.listarTodos({ status: "active" });
+ */
+export declare class Items {
+    private readonly client;
+    constructor(client: AlegraClient);
+    /** Lista una sola página de ítems. */
+    listar(params?: ParametrosItems): Promise<Item[]>;
+    /** Obtiene un ítem por su id. */
+    obtener(id: string): Promise<Item>;
+    /** Recorre todos los ítems página por página. */
+    paginar(params?: ParametrosItems): AsyncGenerator<Item[], void, unknown>;
+    /** Descarga todos los ítems que cumplan el filtro. */
+    listarTodos(params?: ParametrosItems): Promise<Item[]>;
+}

package/dist/resources/items.js

@@ -0,0 +1,40 @@
+import { collectAll, paginate } from "../pagination.js";
+/**
+ * Recurso de ítems (productos y servicios).
+ *
+ * @example
+ * const items = new Items(alegra);
+ * const todos = await items.listarTodos({ status: "active" });
+ */
+export class Items {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /** Lista una sola página de ítems. */
+    listar(params = {}) {
+        return this.client.request("items", { query: { ...params } });
+    }
+    /** Obtiene un ítem por su id. */
+    obtener(id) {
+        return this.client.request(`items/${encodeURIComponent(id)}`);
+    }
+    /** Recorre todos los ítems página por página. */
+    paginar(params = {}) {
+        const { start, limit, ...query } = params;
+        return paginate(this.client, "items", {
+            start,
+            limit,
+            query: query,
+        });
+    }
+    /** Descarga todos los ítems que cumplan el filtro. */
+    listarTodos(params = {}) {
+        const { start, limit, ...query } = params;
+        return collectAll(this.client, "items", {
+            start,
+            limit,
+            query: query,
+        });
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Tipos de los objetos de la API de Alegra usados por este cliente.
+ *
+ * Los tipos reflejan los campos que la API devuelve con más frecuencia. No pretenden
+ * ser exhaustivos: la API puede incluir campos adicionales según el plan y la
+ * configuración de cada cuenta, por eso las interfaces admiten propiedades extra.
+ */
+/** Estado activo/inactivo común a varios recursos. */
+export type EstadoRecurso = "active" | "inactive";
+/** Moneda tal como la expone Alegra. */
+export interface Moneda {
+    code: string;
+    symbol?: string;
+}
+/** Precio de un ítem dentro de una lista de precios. */
+export interface PrecioItem {
+    idPriceList?: string;
+    name?: string;
+    type?: string;
+    price: number;
+    currency?: Moneda;
+    main?: boolean;
+    edited?: boolean;
+}
+/** Contacto (cliente o proveedor). */
+export interface Contacto {
+    id: string;
+    name: string;
+    identification?: string | null;
+    email?: string | null;
+    phonePrimary?: string | null;
+    phoneSecondary?: string | null;
+    mobile?: string | null;
+    status?: EstadoRecurso;
+    type?: string[];
+    observations?: string | null;
+    address?: Record<string, unknown> | null;
+    created_at?: string;
+    updated_at?: string;
+    /** Campos adicionales devueltos por la API. */
+    [extra: string]: unknown;
+}
+/** Ítem / producto o servicio. */
+export interface Item {
+    id: string;
+    name: string;
+    description?: string | null;
+    reference?: string | null;
+    status?: EstadoRecurso;
+    price?: PrecioItem[];
+    type?: string;
+    [extra: string]: unknown;
+}
+/** Numeración/plantilla de una factura. */
+export interface NumeracionFactura {
+    id?: string;
+    prefix?: string;
+    number?: string;
+    fullNumber?: string;
+    documentType?: string;
+    isElectronic?: boolean;
+}
+/** Referencia mínima al cliente dentro de una factura. */
+export interface ClienteFactura {
+    id: string;
+    name?: string;
+    identification?: string;
+}
+/** Factura de venta. */
+export interface Factura {
+    id: string;
+    date: string;
+    dueDate?: string;
+    status?: string;
+    subtotal?: number;
+    discount?: number;
+    tax?: number;
+    total: number;
+    totalPaid?: number;
+    balance?: number;
+    numberTemplate?: NumeracionFactura;
+    client?: ClienteFactura;
+    [extra: string]: unknown;
+}
+/** Parámetros de listado con paginación (comunes a los recursos). */
+export interface ParametrosListado {
+    /** Desplazamiento (offset). Por defecto 0. */
+    start?: number;
+    /** Tamaño de página. Máximo permitido por Alegra: 30. */
+    limit?: number;
+    /** Campo por el cual ordenar. */
+    order_field?: string;
+    /** Dirección del orden. */
+    order_direction?: "ASC" | "DESC";
+}
+/** Parámetros específicos para listar contactos. */
+export interface ParametrosContactos extends ParametrosListado {
+    type?: "client" | "provider";
+    identification?: string;
+    query?: string;
+}
+/** Parámetros específicos para listar facturas. */
+export interface ParametrosFacturas extends ParametrosListado {
+    /** Fecha exacta de creación (YYYY-MM-DD). */
+    date?: string;
+    /** Creadas en o después de (YYYY-MM-DD). */
+    date_afterOrNow?: string;
+    /** Creadas en o antes de (YYYY-MM-DD). */
+    date_beforeOrNow?: string;
+    /** Estado: open, closed, draft, void (admite lista separada por comas). */
+    status?: string;
+    client_id?: string;
+}
+/** Parámetros específicos para listar ítems. */
+export interface ParametrosItems extends ParametrosListado {
+    name?: string;
+    reference?: string;
+    query?: string;
+    status?: EstadoRecurso;
+}

package/dist/types.js

@@ -0,0 +1,8 @@
+/**
+ * Tipos de los objetos de la API de Alegra usados por este cliente.
+ *
+ * Los tipos reflejan los campos que la API devuelve con más frecuencia. No pretenden
+ * ser exhaustivos: la API puede incluir campos adicionales según el plan y la
+ * configuración de cada cuenta, por eso las interfaces admiten propiedades extra.
+ */
+export {};

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "alegra-api-client",
+  "version": "0.1.0",
+  "description": "Cliente ligero y tipado para la API de Alegra (contactos, ítems y facturas): autenticación, paginación y manejo de rate limits.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint:types": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "alegra",
+    "alegra-api",
+    "facturacion",
+    "contabilidad",
+    "api-client",
+    "typescript"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  },
+  "author": "Gary Dormoi",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/garydormoi/alegra-api-client.git"
+  },
+  "homepage": "https://github.com/garydormoi/alegra-api-client#readme",
+  "bugs": {
+    "url": "https://github.com/garydormoi/alegra-api-client/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}