@beel_es/sdk 1.3.0 → 2.1.0

package/dist/index.mjs

@@ -1,54 +1,88 @@
 // src/http/client.ts
 import createClient from "openapi-fetch";
 
+// src/core/defaults.ts
+var DEFAULT_BASE_URL = "https://app.beel.es/api";
+var DEFAULT_MAX_RETRIES = 3;
+var DEFAULT_RETRY_DELAY_MS = 500;
+var DEFAULT_MAX_RETRY_DELAY_MS = 3e4;
+var DEFAULT_AUTO_IDEMPOTENCY_KEY = true;
+
+// src/http/headers.ts
+var IDEMPOTENCY_KEY_HEADER = "Idempotency-Key";
+var IDEMPOTENCY_REPLAY_HEADER = "Idempotency-Replay";
+var RETRY_AFTER_HEADER = "Retry-After";
+var AUTHORIZATION_HEADER = "Authorization";
+var CONTENT_TYPE_HEADER = "Content-Type";
+var JSON_CONTENT_TYPE = "application/json";
+var EMPTY_JSON_BODY = "{}";
+
 // src/http/middleware.ts
 import { randomUUID } from "crypto";
 
+// src/core/http-status.ts
+var HttpStatus = {
+  UNAUTHORIZED: 401,
+  FORBIDDEN: 403,
+  NOT_FOUND: 404,
+  CONFLICT: 409,
+  UNPROCESSABLE_ENTITY: 422,
+  TOO_MANY_REQUESTS: 429,
+  /** First status of the 5xx range: the server failed, not the request. */
+  SERVER_ERROR_MIN: 500
+};
+function isServerErrorStatus(status) {
+  return status >= HttpStatus.SERVER_ERROR_MIN;
+}
+
 // src/core/errors.ts
+var DEFAULT_RATE_LIMIT_RETRY_AFTER_SECONDS = 60;
 var BeeLApiError = class extends Error {
-  constructor(message, statusCode, code, details, requestId) {
+  constructor(message, statusCode, code, details, requestId, apiCode) {
     super(message);
     this.name = "BeeLApiError";
     this.statusCode = statusCode;
     this.code = code;
+    this.apiCode = apiCode ?? code;
     this.details = details;
     this.requestId = requestId;
   }
 };
 var BeeLRateLimitError = class extends BeeLApiError {
-  constructor(message, retryAfterSeconds, requestId) {
-    super(message, 429, "RATE_LIMIT_EXCEEDED", void 0, requestId);
+  constructor(message, retryAfterSeconds, requestId, apiCode) {
+    super(message, HttpStatus.TOO_MANY_REQUESTS, "RATE_LIMIT_EXCEEDED", void 0, requestId, apiCode);
     this.name = "BeeLRateLimitError";
     this.retryAfterSeconds = retryAfterSeconds;
   }
 };
 var BeeLValidationError = class extends BeeLApiError {
-  constructor(message, details, requestId) {
-    super(message, 422, "UNPROCESSABLE_ENTITY", details, requestId);
+  constructor(message, details, requestId, apiCode) {
+    super(message, HttpStatus.UNPROCESSABLE_ENTITY, "UNPROCESSABLE_ENTITY", details, requestId, apiCode);
     this.name = "BeeLValidationError";
   }
 };
 var BeeLAuthError = class extends BeeLApiError {
-  constructor(message, statusCode, requestId) {
+  constructor(message, statusCode, requestId, apiCode) {
     super(
       message,
       statusCode,
-      statusCode === 401 ? "UNAUTHORIZED" : "FORBIDDEN",
+      statusCode === HttpStatus.UNAUTHORIZED ? "UNAUTHORIZED" : "FORBIDDEN",
       void 0,
-      requestId
+      requestId,
+      apiCode
     );
     this.name = "BeeLAuthError";
   }
 };
 var BeeLNotFoundError = class extends BeeLApiError {
-  constructor(message, requestId) {
-    super(message, 404, "NOT_FOUND", void 0, requestId);
+  constructor(message, requestId, apiCode) {
+    super(message, HttpStatus.NOT_FOUND, "NOT_FOUND", void 0, requestId, apiCode);
     this.name = "BeeLNotFoundError";
   }
 };
 var BeeLConflictError = class extends BeeLApiError {
-  constructor(message, requestId) {
-    super(message, 409, "CONFLICT", void 0, requestId);
+  constructor(message, requestId, apiCode, details) {
+    super(message, HttpStatus.CONFLICT, "CONFLICT", details, requestId, apiCode);
     this.name = "BeeLConflictError";
   }
 };
@@ -56,52 +90,60 @@ function throwApiError(status, body) {
   const parsed = body;
   const errorData = parsed?.error ?? parsed;
   const message = errorData?.message ?? `API error ${status}`;
-  const code = errorData?.code ?? "UNKNOWN";
+  const apiCode = errorData?.code;
   const details = errorData?.details;
   const requestId = parsed?.meta?.request_id;
   switch (status) {
-    case 401:
-    case 403:
-      throw new BeeLAuthError(message, status, requestId);
-    case 404:
-      throw new BeeLNotFoundError(message, requestId);
-    case 409:
-      throw new BeeLConflictError(message, requestId);
-    case 422:
-      throw new BeeLValidationError(message, details, requestId);
-    case 429: {
-      const retryAfter = errorData?.retry_after ?? 60;
-      throw new BeeLRateLimitError(message, retryAfter, requestId);
+    case HttpStatus.UNAUTHORIZED:
+    case HttpStatus.FORBIDDEN:
+      throw new BeeLAuthError(message, status, requestId, apiCode);
+    case HttpStatus.NOT_FOUND:
+      throw new BeeLNotFoundError(message, requestId, apiCode);
+    case HttpStatus.CONFLICT:
+      throw new BeeLConflictError(message, requestId, apiCode, details);
+    case HttpStatus.UNPROCESSABLE_ENTITY:
+      throw new BeeLValidationError(message, details, requestId, apiCode);
+    case HttpStatus.TOO_MANY_REQUESTS: {
+      const retryAfter = errorData?.retry_after ?? DEFAULT_RATE_LIMIT_RETRY_AFTER_SECONDS;
+      throw new BeeLRateLimitError(message, retryAfter, requestId, apiCode);
     }
     default:
-      throw new BeeLApiError(message, status, code, details, requestId);
+      throw new BeeLApiError(message, status, apiCode ?? "UNKNOWN", details, requestId);
   }
 }
 
 // src/http/middleware.ts
-var requestMiddleware = {
-  async onRequest({ request }) {
-    const method = request.method;
-    if (["POST", "PUT", "PATCH"].includes(method)) {
-      const hasBody = request.headers.get("content-type")?.includes("application/json");
-      if (!hasBody) {
-        const clone = new Request(request, {
-          body: request.body ?? "{}",
-          headers: new Headers(request.headers)
-        });
-        clone.headers.set("Content-Type", "application/json");
-        if (method === "POST" && !clone.headers.has("Idempotency-Key")) {
-          clone.headers.set("Idempotency-Key", randomUUID());
+var METHODS_WITH_JSON_BODY = /* @__PURE__ */ new Set(["POST", "PUT", "PATCH"]);
+var METHODS_WITH_AUTO_IDEMPOTENCY_KEY = /* @__PURE__ */ new Set(["POST"]);
+function newIdempotencyKey() {
+  return randomUUID();
+}
+function createRequestMiddleware(options) {
+  const addKeyIfMissing = (request) => {
+    if (options.autoIdempotencyKey && METHODS_WITH_AUTO_IDEMPOTENCY_KEY.has(request.method) && !request.headers.has(IDEMPOTENCY_KEY_HEADER)) {
+      request.headers.set(IDEMPOTENCY_KEY_HEADER, newIdempotencyKey());
+    }
+  };
+  return {
+    async onRequest({ request }) {
+      if (METHODS_WITH_JSON_BODY.has(request.method)) {
+        const hasBody = request.headers.get(CONTENT_TYPE_HEADER)?.includes(JSON_CONTENT_TYPE);
+        if (!hasBody) {
+          const clone = new Request(request, {
+            body: request.body ?? EMPTY_JSON_BODY,
+            headers: new Headers(request.headers)
+          });
+          clone.headers.set(CONTENT_TYPE_HEADER, JSON_CONTENT_TYPE);
+          addKeyIfMissing(clone);
+          return clone;
         }
-        return clone;
       }
+      addKeyIfMissing(request);
+      return request;
     }
-    if (method === "POST" && !request.headers.has("Idempotency-Key")) {
-      request.headers.set("Idempotency-Key", randomUUID());
-    }
-    return request;
-  }
-};
+  };
+}
+var requestMiddleware = createRequestMiddleware({ autoIdempotencyKey: true });
 var errorMiddleware = {
   async onResponse({ response }) {
     if (!response.ok) {
@@ -111,31 +153,119 @@ var errorMiddleware = {
     return response;
   }
 };
-function createRetryMiddleware(options) {
-  return {
-    async onError({ error, request }) {
-      if (!(error instanceof BeeLApiError)) return;
-      if (!(error instanceof BeeLRateLimitError) && error.statusCode < 500) return;
-      for (let attempt = 0; attempt < options.maxRetries; attempt++) {
-        const delay = error instanceof BeeLRateLimitError ? error.retryAfterSeconds * 1e3 : Math.min(
-          options.initialDelayMs * Math.pow(2, attempt) + Math.random() * options.initialDelayMs,
-          options.maxDelayMs
-        );
-        await new Promise((r) => setTimeout(r, delay));
-        try {
-          if (request.method === "POST") {
-            request.headers.set("Idempotency-Key", randomUUID());
-          }
-          const response = await fetch(request.clone());
-          if (response.ok) return response;
-          const body = await response.json().catch(() => null);
-          throwApiError(response.status, body);
-        } catch (retryError) {
-          if (!(retryError instanceof BeeLApiError)) throw retryError;
-          if (!(retryError instanceof BeeLRateLimitError) && retryError.statusCode < 500) throw retryError;
-          if (attempt === options.maxRetries - 1) throw retryError;
-        }
+
+// src/core/retry.ts
+function sleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(signal.reason);
+      return;
+    }
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(signal.reason);
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+function computeBackoffDelayMs(attempt, options, random = Math.random) {
+  const exponentialDelay = options.initialDelayMs * Math.pow(2, attempt);
+  const jitter = random() * options.initialDelayMs;
+  return Math.min(exponentialDelay + jitter, options.maxDelayMs);
+}
+
+// src/core/error-codes.ts
+var BeeLErrorCodes = {
+  /**
+   * `409`: a live standard or simplified invoice with the same `external_ref` already exists
+   * in this environment. Look it up with `invoices.list({ external_ref })`.
+   */
+  INVOICE_DUPLICATE_EXTERNAL_REFERENCE: "INVOICE_DUPLICATE_EXTERNAL_REFERENCE",
+  /**
+   * `409`: the first request with this `Idempotency-Key` is still being processed. Retry with
+   * the same key after `Retry-After`; the client does so automatically.
+   */
+  IDEMPOTENCY_KEY_PROCESSING: "IDEMPOTENCY_KEY_PROCESSING",
+  /** `409`: the `Idempotency-Key` was already used with a different body. Use a new key. */
+  IDEMPOTENCY_KEY_MISMATCH: "IDEMPOTENCY_KEY_MISMATCH"
+};
+
+// src/http/retry-policy.ts
+var MS_PER_SECOND = 1e3;
+var READ_ONLY_METHODS = /* @__PURE__ */ new Set(["GET", "HEAD", "OPTIONS"]);
+var IDEMPOTENCY_PROCESSING_DEFAULT_WAIT_MS = 2 * MS_PER_SECOND;
+var NO_RETRY = { retry: false };
+function isReplaySafe(request) {
+  return READ_ONLY_METHODS.has(request.method) || request.headers.has(IDEMPOTENCY_KEY_HEADER);
+}
+function parseRetryAfterMs(value, now = Date.now()) {
+  if (value === null || value.trim() === "") return void 0;
+  const seconds = Number(value);
+  if (Number.isFinite(seconds)) return Math.max(0, seconds * MS_PER_SECOND);
+  const date = Date.parse(value);
+  return Number.isNaN(date) ? void 0 : Math.max(0, date - now);
+}
+function isAbort(error) {
+  return error instanceof Error && error.name === "AbortError";
+}
+async function errorCodeOf(response) {
+  const body = await response.clone().json().catch(() => null);
+  return body?.error?.code;
+}
+async function decideRetry(request, outcome, attempt, options) {
+  const backoff = () => computeBackoffDelayMs(attempt, options);
+  const capped = (delayMs) => ({
+    retry: true,
+    delayMs: Math.min(delayMs, options.maxDelayMs)
+  });
+  if (request.signal?.aborted) return NO_RETRY;
+  if ("error" in outcome) {
+    if (isAbort(outcome.error) || !isReplaySafe(request)) return NO_RETRY;
+    return capped(backoff());
+  }
+  const { response } = outcome;
+  const retryAfterMs = parseRetryAfterMs(response.headers.get(RETRY_AFTER_HEADER));
+  if (response.status === HttpStatus.TOO_MANY_REQUESTS) {
+    return capped(retryAfterMs ?? backoff());
+  }
+  if (response.status === HttpStatus.CONFLICT && request.headers.has(IDEMPOTENCY_KEY_HEADER) && await errorCodeOf(response) === BeeLErrorCodes.IDEMPOTENCY_KEY_PROCESSING) {
+    return capped(retryAfterMs ?? IDEMPOTENCY_PROCESSING_DEFAULT_WAIT_MS);
+  }
+  if (isServerErrorStatus(response.status)) {
+    const isStoredReplay = response.headers.get(IDEMPOTENCY_REPLAY_HEADER) === "true";
+    if (isStoredReplay || !isReplaySafe(request)) return NO_RETRY;
+    return capped(retryAfterMs ?? backoff());
+  }
+  return NO_RETRY;
+}
+
+// src/http/retrying-fetch.ts
+var globalFetch = (request, init) => globalThis.fetch(request, init);
+async function discard(response) {
+  await response.body?.cancel().catch(() => void 0);
+}
+function createRetryingFetch(options, dependencies = {}) {
+  const attemptFetch = dependencies.fetch ?? globalFetch;
+  const wait = dependencies.sleep ?? sleep;
+  return async (request, init) => {
+    for (let attempt = 0; ; attempt++) {
+      let outcome;
+      try {
+        outcome = { response: await attemptFetch(request.clone(), init) };
+      } catch (error) {
+        outcome = { error };
+      }
+      const decision = attempt < options.maxRetries ? await decideRetry(request, outcome, attempt, options) : { retry: false };
+      if (!decision.retry) {
+        if ("error" in outcome) throw outcome.error;
+        return outcome.response;
       }
+      if ("response" in outcome) await discard(outcome.response);
+      await wait(decision.delayMs, request.signal ?? void 0);
     }
   };
 }
@@ -143,20 +273,22 @@ function createRetryMiddleware(options) {
 // src/http/client.ts
 function createBeeLClient(config) {
   const client = createClient({
-    baseUrl: config.baseUrl ?? "https://app.beel.es/api",
+    baseUrl: config.baseUrl ?? DEFAULT_BASE_URL,
     headers: {
-      Authorization: `Bearer ${config.apiKey}`
-    }
+      [AUTHORIZATION_HEADER]: `Bearer ${config.apiKey}`
+    },
+    fetch: createRetryingFetch({
+      maxRetries: config.maxRetries ?? DEFAULT_MAX_RETRIES,
+      initialDelayMs: config.retryDelayMs ?? DEFAULT_RETRY_DELAY_MS,
+      maxDelayMs: config.maxRetryDelayMs ?? DEFAULT_MAX_RETRY_DELAY_MS
+    })
   });
-  client.use(requestMiddleware);
-  client.use(errorMiddleware);
   client.use(
-    createRetryMiddleware({
-      maxRetries: config.maxRetries ?? 3,
-      initialDelayMs: config.retryDelayMs ?? 500,
-      maxDelayMs: config.maxRetryDelayMs ?? 3e4
+    createRequestMiddleware({
+      autoIdempotencyKey: config.autoIdempotencyKey ?? DEFAULT_AUTO_IDEMPOTENCY_KEY
     })
   );
+  client.use(errorMiddleware);
   return client;
 }
 
@@ -168,6 +300,9 @@ var InvoicesResource = class {
   /**
    * List invoices with optional filters and pagination.
    *
+   * @param params - Filters and pagination.
+   * @returns The page of `invoices` and its `pagination`.
+   *
    * @example
    * const { invoices, pagination } = await beel.invoices.list({ status: 'ISSUED', limit: 20 });
    */
@@ -178,6 +313,9 @@ var InvoicesResource = class {
   /**
    * Create a new invoice. An idempotency key is automatically added.
    *
+   * @param body - Type, recipient and lines.
+   * @returns The created invoice.
+   *
    * @example
    * const invoice = await beel.invoices.create({
    *   type: 'STANDARD',
@@ -189,28 +327,52 @@ var InvoicesResource = class {
     const { data } = await this.client.POST("/v1/invoices", { body });
     return data.data;
   }
-  /** Get an invoice by ID. */
+  /**
+   * Get an invoice by ID.
+   *
+   * @param id - Invoice UUID.
+   * @returns The invoice.
+   */
   async get(id) {
     const { data } = await this.client.GET("/v1/invoices/{invoice_id}", { params: { path: { invoice_id: id } } });
     return data.data;
   }
-  /** Update a draft invoice. Only draft invoices can be updated. */
+  /**
+   * Update a draft invoice. Only draft invoices can be updated.
+   *
+   * @param id - Invoice UUID.
+   * @param body - The draft's new content.
+   * @returns The updated invoice.
+   */
   async update(id, body) {
     const { data } = await this.client.PUT("/v1/invoices/{invoice_id}", { params: { path: { invoice_id: id } }, body });
     return data.data;
   }
-  /** Delete a draft invoice. Only draft invoices can be deleted. */
+  /**
+   * Delete a draft invoice. Only draft invoices can be deleted.
+   *
+   * @param id - Invoice UUID.
+   */
   async delete(id) {
     await this.client.DELETE("/v1/invoices/{invoice_id}", { params: { path: { invoice_id: id } } });
   }
-  /** Duplicate an invoice, optionally into a different series. */
+  /**
+   * Duplicate an invoice, optionally into a different series.
+   *
+   * @param id - Invoice UUID.
+   * @param options - `series_id` and `notes` of the copy.
+   * @returns The new draft.
+   */
   async duplicate(id, options) {
     const { data } = await this.client.POST("/v1/invoices/{invoice_id}/duplicate", { params: { path: { invoice_id: id } }, body: options });
     return data.data;
   }
   /**
    * Issue a draft invoice. Assigns an invoice number and triggers VeriFactu submission.
-   * @param options.wait_for_pdf - If true, waits for PDF generation before returning.
+   *
+   * @param id - Invoice UUID.
+   * @param options - `wait_for_pdf: true` to wait for the PDF.
+   * @returns The issued invoice.
    */
   async issue(id, options) {
     const { data } = await this.client.POST("/v1/invoices/{invoice_id}/issue", { params: { path: { invoice_id: id }, query: options } });
@@ -218,19 +380,32 @@ var InvoicesResource = class {
   }
   /**
    * Mark an invoice as paid.
-   * @param options.payment_date - Payment date (defaults to today).
-   * @param options.payment_method - Payment method details.
+   *
+   * @param id - Invoice UUID.
+   * @param options - `payment_date` (default: today) and `payment_method`.
+   * @returns The paid invoice.
    */
   async markPaid(id, options) {
     const { data } = await this.client.POST("/v1/invoices/{invoice_id}/mark-paid", { params: { path: { invoice_id: id } }, body: options });
     return data.data;
   }
-  /** Mark an invoice as sent (e.g. delivered by other means). */
+  /**
+   * Mark an invoice as sent (e.g. delivered by other means).
+   *
+   * @param id - Invoice UUID.
+   * @param options - `sent_at`.
+   * @returns The sent invoice.
+   */
   async markSent(id, options) {
     const { data } = await this.client.POST("/v1/invoices/{invoice_id}/mark-sent", { params: { path: { invoice_id: id } }, body: options });
     return data.data;
   }
-  /** Revert a paid/sent invoice back to issued status. */
+  /**
+   * Revert a paid/sent invoice back to issued status.
+   *
+   * @param id - Invoice UUID.
+   * @returns The invoice, back in `ISSUED`.
+   */
   async revertToIssued(id) {
     const { data } = await this.client.POST("/v1/invoices/{invoice_id}/revert-to-issued", { params: { path: { invoice_id: id } } });
     return data.data;
@@ -238,6 +413,10 @@ var InvoicesResource = class {
   /**
    * Void an issued invoice. Requires a reason (min 10 chars).
    *
+   * @param id - Invoice UUID.
+   * @param params - `reason` (min 10 characters) and optional `void_date`.
+   * @returns The voided invoice.
+   *
    * @example
    * await beel.invoices.void('id', { reason: 'Duplicate invoice sent in error' });
    */
@@ -245,22 +424,45 @@ var InvoicesResource = class {
     const { data } = await this.client.POST("/v1/invoices/{invoice_id}/void", { params: { path: { invoice_id: id } }, body: params });
     return data.data;
   }
-  /** Create a corrective invoice that references the original. */
+  /**
+   * Create a corrective invoice that references the original.
+   *
+   * @param id - UUID of the issued invoice to correct.
+   * @param body - Rectification type, code, reason and lines.
+   * @returns The corrective invoice.
+   */
   async createCorrective(id, body) {
     const { data } = await this.client.POST("/v1/invoices/{invoice_id}/corrective", { params: { path: { invoice_id: id } }, body });
     return data.data;
   }
-  /** Schedule a draft invoice to be issued on a future date. */
+  /**
+   * Schedule a draft invoice to be issued on a future date.
+   *
+   * @param id - UUID of the draft.
+   * @param params - `scheduled_for` and optional `action`.
+   * @returns The scheduled invoice.
+   */
   async schedule(id, params) {
     const { data } = await this.client.POST("/v1/invoices/{invoice_id}/schedule", { params: { path: { invoice_id: id } }, body: params });
     return data.data;
   }
-  /** Cancel a scheduled invoice, returning it to draft. */
+  /**
+   * Cancel a scheduled invoice, returning it to draft.
+   *
+   * @param id - Invoice UUID.
+   * @returns The invoice, back in draft.
+   */
   async unschedule(id) {
     const { data } = await this.client.POST("/v1/invoices/{invoice_id}/unschedule", { params: { path: { invoice_id: id } } });
     return data.data;
   }
-  /** Change the scheduled date of a scheduled invoice. */
+  /**
+   * Change the scheduled date of a scheduled invoice.
+   *
+   * @param id - Invoice UUID.
+   * @param params - New `scheduled_for`.
+   * @returns The rescheduled invoice.
+   */
   async reschedule(id, params) {
     const { data } = await this.client.PATCH("/v1/invoices/{invoice_id}/reschedule", { params: { path: { invoice_id: id } }, body: params });
     return data.data;
@@ -268,12 +470,21 @@ var InvoicesResource = class {
   /**
    * Get a pre-signed URL to download the invoice PDF.
    * The URL expires in 5 minutes. Use `beel.downloadPdf(id)` for a simpler Buffer download.
+   *
+   * @param id - Invoice UUID.
+   * @returns `download_url`, `expires_in_seconds` and `file_name`.
    */
   async getPdf(id) {
     const { data } = await this.client.GET("/v1/invoices/{invoice_id}/pdf", { params: { path: { invoice_id: id } } });
     return data.data;
   }
-  /** Send an invoice by email. Uses the customer's email by default. */
+  /**
+   * Send an invoice by email. Uses the customer's email by default.
+   *
+   * @param id - Invoice UUID.
+   * @param options - Recipients, subject and message.
+   * @returns The delivery record.
+   */
   async sendEmail(id, options) {
     const { data } = await this.client.POST("/v1/invoices/{invoice_id}/send", { params: { path: { invoice_id: id } }, body: options });
     return data.data;
@@ -288,6 +499,9 @@ var CustomersResource = class {
   /**
    * List customers with optional filters and pagination.
    *
+   * @param params - Filters and pagination.
+   * @returns The page of `customers` and its `pagination`.
+   *
    * @example
    * const { customers, pagination } = await beel.customers.list({ search: 'Acme', limit: 10 });
    */
@@ -298,6 +512,9 @@ var CustomersResource = class {
   /**
    * Create a new customer.
    *
+   * @param body - Legal name, NIF and address.
+   * @returns The created customer.
+   *
    * @example
    * const customer = await beel.customers.create({
    *   legal_name: 'Acme SL',
@@ -309,17 +526,32 @@ var CustomersResource = class {
     const { data } = await this.client.POST("/v1/customers", { body });
     return data.data;
   }
-  /** Get a customer by ID. */
+  /**
+   * Get a customer by ID.
+   *
+   * @param id - Customer UUID.
+   * @returns The customer.
+   */
   async get(id) {
     const { data } = await this.client.GET("/v1/customers/{customer_id}", { params: { path: { customer_id: id } } });
     return data.data;
   }
-  /** Update a customer. Only provided fields are changed. */
+  /**
+   * Update a customer. Only provided fields are changed.
+   *
+   * @param id - Customer UUID.
+   * @param body - Fields to change.
+   * @returns The updated customer.
+   */
   async update(id, body) {
     const { data } = await this.client.PUT("/v1/customers/{customer_id}", { params: { path: { customer_id: id } }, body });
     return data.data;
   }
-  /** Deactivate (soft-delete) a customer. */
+  /**
+   * Deactivate (soft-delete) a customer.
+   *
+   * @param id - Customer UUID.
+   */
   async deactivate(id) {
     await this.client.DELETE("/v1/customers/{customer_id}", { params: { path: { customer_id: id } } });
   }
@@ -333,6 +565,9 @@ var ProductsResource = class {
   /**
    * List products with optional filters and pagination.
    *
+   * @param params - Filters and pagination.
+   * @returns The page of `products` and its `pagination`.
+   *
    * @example
    * const { products, pagination } = await beel.products.list({ category: 'SERVICE' });
    */
@@ -343,6 +578,9 @@ var ProductsResource = class {
   /**
    * Create a new product or service.
    *
+   * @param body - Name, category, price and main tax.
+   * @returns The created product.
+   *
    * @example
    * const product = await beel.products.create({
    *   name: 'Consulting',
@@ -356,23 +594,42 @@ var ProductsResource = class {
     const { data } = await this.client.POST("/v1/products", { body });
     return data.data;
   }
-  /** Get a product by ID. */
+  /**
+   * Get a product by ID.
+   *
+   * @param id - Product UUID.
+   * @returns The product.
+   */
   async get(id) {
     const { data } = await this.client.GET("/v1/products/{product_id}", { params: { path: { product_id: id } } });
     return data.data;
   }
-  /** Update a product. Only provided fields are changed. */
+  /**
+   * Update a product. Only provided fields are changed.
+   *
+   * @param id - Product UUID.
+   * @param body - Fields to change.
+   * @returns The updated product.
+   */
   async update(id, body) {
     const { data } = await this.client.PUT("/v1/products/{product_id}", { params: { path: { product_id: id } }, body });
     return data.data;
   }
-  /** Delete a product permanently. */
+  /**
+   * Delete a product permanently.
+   *
+   * @param id - Product UUID.
+   */
   async delete(id) {
     await this.client.DELETE("/v1/products/{product_id}", { params: { path: { product_id: id } } });
   }
   /**
    * Search products by name or code. Returns up to `limit` results.
    *
+   * @param q - Text to search in name or code.
+   * @param limit - Maximum results.
+   * @returns The matching products, as a bare array.
+   *
    * @example
    * const results = await beel.products.search('consulting', 5);
    */
@@ -387,37 +644,68 @@ var ConfigurationResource = class {
   constructor(client) {
     this.client = client;
   }
-  /** Get the current tax configuration (default VAT, IRPF, etc.). */
+  /**
+   * Get the tax configuration (default VAT, IRPF…) of the focused company.
+   *
+   * @returns The tax configuration.
+   */
   async getTaxConfig() {
     const { data } = await this.client.GET("/v1/configuration/taxes");
     return data.data;
   }
-  /** Update tax configuration. */
+  /**
+   * Replace the tax configuration of the focused company.
+   *
+   * @param body - The complete tax configuration.
+   * @returns The stored configuration.
+   */
   async updateTaxConfig(body) {
     const { data } = await this.client.PUT("/v1/configuration/taxes", { body });
     return data.data;
   }
-  /** Get available tax types (IVA/IGIC rates, IRPF types, equivalence surcharges). */
+  /**
+   * Tax types the API accepts (IVA/IGIC rates, IRPF types, equivalence surcharges).
+   *
+   * @returns The tax types catalog.
+   */
   async getTaxTypes() {
     const { data } = await this.client.GET("/v1/configuration/tax-types");
     return data.data;
   }
-  /** Get invoice customization options (logo, colors, footer text, etc.). */
+  /**
+   * Invoice customization options (templates, colors…).
+   *
+   * @returns The customization options.
+   */
   async getInvoiceCustomizationOptions() {
     const { data } = await this.client.GET("/v1/configuration/invoice-customization-options");
     return data.data;
   }
-  /** Update the user's preferred language (es, en, ca). */
+  /**
+   * Update the preferred language of the signed-in person.
+   *
+   * @param language - `es`, `en` or `ca`.
+   * @returns The updated preferences.
+   */
   async updateLanguage(language) {
     const { data } = await this.client.PUT("/v1/configuration/language", { body: { language } });
     return data.data;
   }
-  /** Get VeriFactu configuration (enabled, certificate status, etc.). */
+  /**
+   * Get the VeriFactu configuration of the focused company.
+   *
+   * @returns The VeriFactu configuration.
+   */
   async getVerifactu() {
     const { data } = await this.client.GET("/v1/configuration/verifactu");
     return data.data;
   }
-  /** Update VeriFactu configuration. */
+  /**
+   * Update the VeriFactu configuration of the focused company.
+   *
+   * @param body - `{ enabled }`.
+   * @returns The updated configuration.
+   */
   async updateVerifactu(body) {
     const { data } = await this.client.PUT("/v1/configuration/verifactu", { body });
     return data.data;
@@ -427,19 +715,47 @@ var CatalogsResource = class {
   constructor(client) {
     this.client = client;
   }
-  /** Tax types the API accepts. Canonical form of `configuration/tax-types`. */
+  /**
+   * Who the API key belongs to: its `account_id` — the starting point to list the
+   * account's companies — plus the person's email, name and language, and the credential.
+   * Needs no scope, so it also confirms that a key works.
+   *
+   * @returns The identity of the credential.
+   *
+   * @example
+   * ```typescript
+   * const { account_id } = await beel.catalogs.identity();
+   * const { companies } = await beel.account(account_id).companies.list();
+   * ```
+   */
+  async identity() {
+    const { data } = await this.client.GET("/v1/me/identity");
+    return data.data;
+  }
+  /**
+   * Tax types the API accepts. Canonical form of `configuration/tax-types`.
+   *
+   * @returns The tax types catalog.
+   */
   async taxTypes() {
     const { data } = await this.client.GET("/v1/tax-types");
     return data.data;
   }
-  /** Invoice customization options. Canonical form of the `configuration` read. */
+  /**
+   * Invoice PDF templates and customization options. Canonical form of the `configuration` read.
+   *
+   * @returns The customization options.
+   */
   async invoiceCustomizationOptions() {
     const { data } = await this.client.GET("/v1/invoice-customization-options");
     return data.data;
   }
   /**
-   * The signed-in person's preferences. Canonical form of
+   * Update the signed-in person's preferences. Canonical form of
    * `PUT /v1/configuration/language`: the language belongs to the person, not to a company.
+   *
+   * @param body - Preferences to change, e.g. `{ language: 'es' }`.
+   * @returns The updated preferences.
    */
   async updateMe(body) {
     const { data } = await this.client.PATCH("/v1/me", { body });
@@ -455,6 +771,9 @@ var SeriesResource = class {
   /**
    * List all invoice series. Optionally filter by active status.
    *
+   * @param active - Only active (`true`) or inactive (`false`) series; all when omitted.
+   * @returns The series.
+   *
    * @example
    * const series = await beel.series.list();
    * const activeSeries = await beel.series.list(true);
@@ -465,12 +784,23 @@ var SeriesResource = class {
     });
     return data.data;
   }
-  /** Create a new invoice series (e.g. "A-2026", "RECT"). */
+  /**
+   * Create a new invoice series (e.g. "A-2026", "RECT").
+   *
+   * @param body - Code, name and format.
+   * @returns The created series.
+   */
   async create(body) {
     const { data } = await this.client.POST("/v1/configuration/series", { body });
     return data.data;
   }
-  /** Update a series (name, description, etc.). */
+  /**
+   * Update a series (name, description, etc.).
+   *
+   * @param id - Series UUID.
+   * @param body - Fields to change.
+   * @returns The updated series.
+   */
   async update(id, body) {
     const { data } = await this.client.PUT("/v1/configuration/series/{series_id}", {
       params: { path: { series_id: id } },
@@ -478,13 +808,22 @@ var SeriesResource = class {
     });
     return data.data;
   }
-  /** Delete an invoice series. Only empty series can be deleted. */
+  /**
+   * Delete an invoice series. Only empty series can be deleted.
+   *
+   * @param id - Series UUID.
+   */
   async delete(id) {
     await this.client.DELETE("/v1/configuration/series/{series_id}", {
       params: { path: { series_id: id } }
     });
   }
-  /** Set a series as the default for new invoices. */
+  /**
+   * Set a series as the default for new invoices.
+   *
+   * @param id - Series UUID.
+   * @returns The series.
+   */
   async setDefault(id) {
     const { data } = await this.client.POST("/v1/configuration/series/{series_id}/default", {
       params: { path: { series_id: id } }
@@ -501,6 +840,9 @@ var NifResource = class {
   /**
    * Validate a Spanish NIF/CIF against the AEAT tax registry.
    *
+   * @param nif - The NIF/CIF to validate.
+   * @returns Whether it is valid and, when the register knows it, its holder's name.
+   *
    * @example
    * const result = await beel.nif.validate('B12345678');
    * console.log(result.valid, result.name);
@@ -516,24 +858,47 @@ var AccountsResource = class {
   constructor(client) {
     this.client = client;
   }
-  /** List accounts reachable with this API key (cursor-paginated). */
+  /**
+   * List the accounts you provisioned, newest first. Cursor-paginated: pass the
+   * `next_cursor` of one page as `cursor` of the next until it is `null`.
+   *
+   * @param params - `status`, `external_ref` (exact), `limit`, `cursor`.
+   * @returns The `accounts` of the page and `next_cursor`.
+   */
   async list(params) {
     const { data } = await this.client.GET("/v1/accounts", { params: { query: params } });
     return data.data;
   }
-  /** Provision a new managed account. */
+  /**
+   * Provision a new managed account. Idempotent by `external_ref`: sending the same one
+   * again returns the same account. Answers with the provisioning result — the account id,
+   * its status and, when one is issued, the claim link — not with the account summary.
+   *
+   * @param body - `external_ref` and the holder's details.
+   * @returns `account_id`, `status` and the claim link state.
+   */
   async provision(body) {
     const { data } = await this.client.POST("/v1/accounts", { body });
     return data.data;
   }
-  /** Get a managed account by ID. */
+  /**
+   * Get a managed account.
+   *
+   * @param accountId - Account UUID.
+   * @returns The account summary.
+   */
   async get(accountId) {
     const { data } = await this.client.GET("/v1/accounts/{account_id}", {
       params: { path: { account_id: accountId } }
     });
     return data.data;
   }
-  /** Alias of `beel.account(accountId)` — returns an account-scoped facade. */
+  /**
+   * Alias of `beel.account(accountId)`: the operations scoped to one account.
+   *
+   * @param accountId - Account UUID.
+   * @returns The account scope. No request is made.
+   */
   scope(accountId) {
     return new AccountScope(this.client, accountId);
   }
@@ -550,28 +915,49 @@ var AccountScope = class {
   path() {
     return { account_id: this.accountId };
   }
-  /** Get the account summary. */
+  /**
+   * Get the account summary.
+   *
+   * @returns The account summary.
+   */
   async get() {
     const { data } = await this.client.GET("/v1/accounts/{account_id}", { params: { path: this.path() } });
     return data.data;
   }
-  /** Provisioning usage counters (accounts, NIFs) for billing purposes. */
+  /**
+   * Provisioning usage counters for billing: provisioned accounts and NIFs.
+   *
+   * @returns `provisioned_accounts` and `nifs`.
+   */
   async usage() {
     const { data } = await this.client.GET("/v1/accounts/{account_id}/usage", { params: { path: this.path() } });
     return data.data;
   }
-  /** Change the manager's access level over this account. */
+  /**
+   * Change the access level you keep over this account. Raising it is only possible while
+   * the account is unclaimed.
+   *
+   * @param body - The new `access_level`.
+   */
   async changeAccessLevel(body) {
     await this.client.PATCH("/v1/accounts/{account_id}/access-level", {
       params: { path: this.path() },
       body
     });
   }
-  /** End the management relationship with this account. */
+  /**
+   * End your management of this account: you lose access, and the holder keeps the
+   * account, its NIFs and its invoices.
+   */
   async endManagement() {
     await this.client.DELETE("/v1/accounts/{account_id}/management", { params: { path: this.path() } });
   }
-  /** Create a claim token so the end user can take ownership of the account. */
+  /**
+   * Issue a single-use claim token so the account's holder can take ownership.
+   *
+   * @param body - `email` when the account has no holder yet; omit to re-issue.
+   * @returns `claim_token`, `claim_url` and `expires_at`.
+   */
   async createClaimToken(body) {
     const { data } = await this.client.POST("/v1/accounts/{account_id}/claim-tokens", {
       params: { path: this.path() },
@@ -579,7 +965,11 @@ var AccountScope = class {
     });
     return data.data;
   }
-  /** Transfer account ownership to an existing member. */
+  /**
+   * Make an existing member the account's owner. Repeatable: it states the desired owner.
+   *
+   * @param body - The member that becomes owner.
+   */
   async setOwner(body) {
     await this.client.PUT("/v1/accounts/{account_id}/owner", {
       params: { path: this.path() },
@@ -592,19 +982,36 @@ var AccountMembersResource = class {
     this.client = client;
     this.accountId = accountId;
   }
+  /**
+   * List the account's members.
+   *
+   * @returns The members (`data.members` of the response), as an array.
+   */
   async list() {
     const { data } = await this.client.GET("/v1/accounts/{account_id}/members", {
       params: { path: { account_id: this.accountId } }
     });
     return data.data.members;
   }
+  /**
+   * Get one member.
+   *
+   * @param memberId - Member UUID.
+   * @returns The member.
+   */
   async get(memberId) {
     const { data } = await this.client.GET("/v1/accounts/{account_id}/members/{member_id}", {
       params: { path: { account_id: this.accountId, member_id: memberId } }
     });
     return data.data;
   }
-  /** Update a member's account role. */
+  /**
+   * Change a member's account role.
+   *
+   * @param memberId - Member UUID.
+   * @param body - The new `account_role`.
+   * @returns The updated member.
+   */
   async update(memberId, body) {
     const { data } = await this.client.PATCH("/v1/accounts/{account_id}/members/{member_id}", {
       params: { path: { account_id: this.accountId, member_id: memberId } },
@@ -612,20 +1019,36 @@ var AccountMembersResource = class {
     });
     return data.data;
   }
-  /** Remove a member from the account. */
+  /**
+   * Remove a member from the account.
+   *
+   * @param memberId - Member UUID.
+   */
   async remove(memberId) {
     await this.client.DELETE("/v1/accounts/{account_id}/members/{member_id}", {
       params: { path: { account_id: this.accountId, member_id: memberId } }
     });
   }
-  /** List a member's per-company grants. */
+  /**
+   * List a member's per-company grants.
+   *
+   * @param memberId - Member UUID.
+   * @returns The `grants` and their `pagination`.
+   */
   async listGrants(memberId) {
     const { data } = await this.client.GET("/v1/accounts/{account_id}/members/{member_id}/grants", {
       params: { path: { account_id: this.accountId, member_id: memberId } }
     });
     return data.data;
   }
-  /** Grant (or replace) a member's permissions over one company. */
+  /**
+   * Grant a member access to one company, or replace the grant it has.
+   *
+   * @param memberId - Member UUID.
+   * @param companyId - Company UUID.
+   * @param body - The `access_level` to grant.
+   * @returns The grant.
+   */
   async putGrant(memberId, companyId, body) {
     const { data } = await this.client.PUT("/v1/accounts/{account_id}/members/{member_id}/grants/{company_id}", {
       params: { path: { account_id: this.accountId, member_id: memberId, company_id: companyId } },
@@ -633,7 +1056,12 @@ var AccountMembersResource = class {
     });
     return data.data;
   }
-  /** Revoke a member's grant over one company. */
+  /**
+   * Revoke a member's access to one company.
+   *
+   * @param memberId - Member UUID.
+   * @param companyId - Company UUID.
+   */
   async removeGrant(memberId, companyId) {
     await this.client.DELETE("/v1/accounts/{account_id}/members/{member_id}/grants/{company_id}", {
       params: { path: { account_id: this.accountId, member_id: memberId, company_id: companyId } }
@@ -645,12 +1073,23 @@ var AccountInvitationsResource = class {
     this.client = client;
     this.accountId = accountId;
   }
+  /**
+   * List the account's invitations.
+   *
+   * @returns The invitations.
+   */
   async list() {
     const { data } = await this.client.GET("/v1/accounts/{account_id}/invitations", {
       params: { path: { account_id: this.accountId } }
     });
     return data.data;
   }
+  /**
+   * Invite someone to join the account.
+   *
+   * @param body - `invited_email` and the `account_role` to grant.
+   * @returns The invitation.
+   */
   async create(body) {
     const { data } = await this.client.POST("/v1/accounts/{account_id}/invitations", {
       params: { path: { account_id: this.accountId } },
@@ -658,12 +1097,23 @@ var AccountInvitationsResource = class {
     });
     return data.data;
   }
+  /**
+   * Get one invitation.
+   *
+   * @param invitationId - Invitation UUID.
+   * @returns The invitation.
+   */
   async get(invitationId) {
     const { data } = await this.client.GET("/v1/accounts/{account_id}/invitations/{invitation_id}", {
       params: { path: { account_id: this.accountId, invitation_id: invitationId } }
     });
     return data.data;
   }
+  /**
+   * Revoke a `PENDING` invitation, so its link stops working.
+   *
+   * @param invitationId - Invitation UUID.
+   */
   async revoke(invitationId) {
     await this.client.DELETE("/v1/accounts/{account_id}/invitations/{invitation_id}", {
       params: { path: { account_id: this.accountId, invitation_id: invitationId } }
@@ -675,12 +1125,24 @@ var AccountWebhooksResource = class {
     this.client = client;
     this.accountId = accountId;
   }
+  /**
+   * List the webhook subscriptions.
+   *
+   * @param params - Pagination.
+   * @returns The `webhooks` and their `pagination`.
+   */
   async list(params) {
     const { data } = await this.client.GET("/v1/accounts/{account_id}/webhooks", {
       params: { path: { account_id: this.accountId }, query: params }
     });
     return data.data;
   }
+  /**
+   * Subscribe an HTTPS endpoint to events.
+   *
+   * @param body - `url` and the `events` to receive.
+   * @returns The subscription, with its signing secret.
+   */
   async create(body) {
     const { data } = await this.client.POST("/v1/accounts/{account_id}/webhooks", {
       params: { path: { account_id: this.accountId } },
@@ -688,12 +1150,25 @@ var AccountWebhooksResource = class {
     });
     return data.data;
   }
+  /**
+   * Get one webhook subscription.
+   *
+   * @param webhookId - Subscription UUID.
+   * @returns The subscription.
+   */
   async get(webhookId) {
     const { data } = await this.client.GET("/v1/accounts/{account_id}/webhooks/{webhook_id}", {
       params: { path: { account_id: this.accountId, webhook_id: webhookId } }
     });
     return data.data;
   }
+  /**
+   * Update a webhook subscription. Only the fields present in `body` change.
+   *
+   * @param webhookId - Subscription UUID.
+   * @param body - Fields to change.
+   * @returns The updated subscription.
+   */
   async update(webhookId, body) {
     const { data } = await this.client.PATCH("/v1/accounts/{account_id}/webhooks/{webhook_id}", {
       params: { path: { account_id: this.accountId, webhook_id: webhookId } },
@@ -701,31 +1176,60 @@ var AccountWebhooksResource = class {
     });
     return data.data;
   }
+  /**
+   * Delete a webhook subscription.
+   *
+   * @param webhookId - Subscription UUID.
+   */
   async delete(webhookId) {
     await this.client.DELETE("/v1/accounts/{account_id}/webhooks/{webhook_id}", {
       params: { path: { account_id: this.accountId, webhook_id: webhookId } }
     });
   }
-  /** Send a test event to the webhook endpoint. */
+  /**
+   * Send a test event to the endpoint. Test deliveries carry `test: true`.
+   *
+   * @param webhookId - Subscription UUID.
+   * @returns The outcome of the delivery.
+   */
   async test(webhookId) {
     const { data } = await this.client.POST("/v1/accounts/{account_id}/webhooks/{webhook_id}/test", {
       params: { path: { account_id: this.accountId, webhook_id: webhookId } }
     });
     return data.data;
   }
-  /** Rotate the webhook signing secret. */
+  /**
+   * Rotate the signing secret. The old secret stops working immediately.
+   *
+   * @param webhookId - Subscription UUID.
+   * @returns The subscription with its new secret.
+   */
   async rotateSecret(webhookId) {
     const { data } = await this.client.POST("/v1/accounts/{account_id}/webhooks/{webhook_id}/secret", {
       params: { path: { account_id: this.accountId, webhook_id: webhookId } }
     });
     return data.data;
   }
+  /**
+   * List the delivery attempts of a subscription.
+   *
+   * @param webhookId - Subscription UUID.
+   * @param params - Filters and pagination.
+   * @returns The deliveries.
+   */
   async listDeliveries(webhookId, params) {
     const { data } = await this.client.GET("/v1/accounts/{account_id}/webhooks/{webhook_id}/deliveries", {
       params: { path: { account_id: this.accountId, webhook_id: webhookId }, query: params }
     });
     return data.data;
   }
+  /**
+   * Retry a failed delivery.
+   *
+   * @param webhookId - Subscription UUID.
+   * @param deliveryId - Delivery UUID.
+   * @returns The new delivery attempt.
+   */
   async retryDelivery(webhookId, deliveryId) {
     const { data } = await this.client.POST("/v1/accounts/{account_id}/webhooks/{webhook_id}/deliveries/{delivery_id}/retry", {
       params: { path: { account_id: this.accountId, webhook_id: webhookId, delivery_id: deliveryId } }
@@ -738,6 +1242,19 @@ var AccountCompaniesResource = class {
     this.client = client;
     this.accountId = accountId;
   }
+  /**
+   * List the account's companies, primary first. Always paginated (20 by default).
+   *
+   * @param params - `search`, `include`, `page`, `limit`.
+   * @returns The `companies` of the page and its `pagination`.
+   *
+   * @example
+   * ```typescript
+   * const { account_id } = await beel.catalogs.identity();
+   * const { companies } = await beel.account(account_id).companies.list({ search: 'B12345678' });
+   * const company = beel.company(companies[0].id!);
+   * ```
+   */
   async list(params) {
     const { data } = await this.client.GET("/v1/accounts/{account_id}/companies", {
       params: { path: { account_id: this.accountId }, query: params }
@@ -747,7 +1264,12 @@ var AccountCompaniesResource = class {
       pagination: data.data?.pagination
     };
   }
-  /** Register a new company (NIF) under the account. */
+  /**
+   * Register a new company (NIF) under the account.
+   *
+   * @param body - NIF, legal name, entity type and address.
+   * @returns The created company.
+   */
   async create(body) {
     const { data } = await this.client.POST("/v1/accounts/{account_id}/companies", {
       params: { path: { account_id: this.accountId } },
@@ -755,7 +1277,11 @@ var AccountCompaniesResource = class {
     });
     return data.data;
   }
-  /** Aggregated per-company stats for the account. */
+  /**
+   * Per-company invoice stats: how many fiscal documents each issued, and when last.
+   *
+   * @returns One entry per company.
+   */
   async stats() {
     const { data } = await this.client.GET("/v1/accounts/{account_id}/companies/stats", {
       params: { path: { account_id: this.accountId } }
@@ -764,6 +1290,38 @@ var AccountCompaniesResource = class {
   }
 };
 
+// src/http/request-options.ts
+function anySignal(signals) {
+  const native = AbortSignal.any;
+  if (native) return native(signals);
+  const controller = new AbortController();
+  for (const signal of signals) {
+    if (signal.aborted) {
+      controller.abort(signal.reason);
+      break;
+    }
+    signal.addEventListener("abort", () => controller.abort(signal.reason), { once: true });
+  }
+  return controller.signal;
+}
+function signalOf(options) {
+  const signals = [];
+  if (options.signal) signals.push(options.signal);
+  if (options.timeoutMs !== void 0) signals.push(AbortSignal.timeout(options.timeoutMs));
+  if (signals.length <= 1) return signals[0];
+  return anySignal(signals);
+}
+function toRequestInit(options) {
+  if (!options) return {};
+  const init = {};
+  if (options.idempotencyKey !== void 0) {
+    init.headers = { [IDEMPOTENCY_KEY_HEADER]: options.idempotencyKey };
+  }
+  const signal = signalOf(options);
+  if (signal) init.signal = signal;
+  return init;
+}
+
 // src/resources/payment-connections.ts
 var CompanyPaymentConnectionsResource = class {
   constructor(client, companyId) {
@@ -773,7 +1331,11 @@ var CompanyPaymentConnectionsResource = class {
   path() {
     return { company_id: this.companyId };
   }
-  /** Every payment connection of this company. */
+  /**
+   * Every payment connection of this company.
+   *
+   * @returns The `connections`.
+   */
   async list() {
     const { data } = await this.client.GET("/v1/companies/{company_id}/payment-connections", {
       params: { path: this.path() }
@@ -784,6 +1346,9 @@ var CompanyPaymentConnectionsResource = class {
    * Start an authorization and get the URL where the NIF's holder approves it.
    *
    * This is the one place the provider slug is used — currently only `stripe`.
+   *
+   * @param body - `{ provider: 'stripe' }`, plus the return URL when needed.
+   * @returns The `authorization_url` to send the NIF's holder to.
    */
   async authorize(body) {
     const { data } = await this.client.POST(
@@ -792,7 +1357,13 @@ var CompanyPaymentConnectionsResource = class {
     );
     return data.data;
   }
-  /** Update one connection, addressed by its UUID. */
+  /**
+   * Update the settings of one connection, addressed by its UUID.
+   *
+   * @param connectionId - Connection UUID, from {@link list}.
+   * @param body - Settings to change.
+   * @returns The updated connection.
+   */
   async update(connectionId, body) {
     const { data } = await this.client.PATCH(
       "/v1/companies/{company_id}/payment-connections/{connection_id}",
@@ -803,13 +1374,20 @@ var CompanyPaymentConnectionsResource = class {
   /**
    * Disconnect one connection. Tokens are revoked and auto-invoicing stops;
    * already-issued invoices are untouched.
+   *
+   * @param connectionId - Connection UUID.
    */
   async disconnect(connectionId) {
     await this.client.DELETE("/v1/companies/{company_id}/payment-connections/{connection_id}", {
       params: { path: { ...this.path(), connection_id: connectionId } }
     });
   }
-  /** The payment events of one connection — where you audit what did and didn't invoice. */
+  /**
+   * The payment events of one connection — where you audit what did and didn't invoice.
+   *
+   * @param connectionId - Connection UUID.
+   * @returns The events resource of that connection. No request is made.
+   */
   events(connectionId) {
     return new CompanyPaymentEventsResource(this.client, this.companyId, connectionId);
   }
@@ -827,6 +1405,9 @@ var CompanyPaymentEventsResource = class {
    * Events of the connection, most recent first. Nothing is hidden by default:
    * skipped events, duplicates and disputes are all returned — narrow with the
    * filters. `charges_only` returns one row per money movement instead.
+   *
+   * @param params - Filters (`needs_action`, `charges_only`…) and pagination.
+   * @returns The `events`, their `pagination` and `counts`.
    */
   async list(params) {
     const { data } = await this.client.GET(
@@ -835,7 +1416,12 @@ var CompanyPaymentEventsResource = class {
     );
     return data.data;
   }
-  /** One event. */
+  /**
+   * Get one event.
+   *
+   * @param eventId - Event UUID.
+   * @returns The event.
+   */
   async get(eventId) {
     const { data } = await this.client.GET(
       "/v1/companies/{company_id}/payment-connections/{connection_id}/events/{event_id}",
@@ -847,6 +1433,9 @@ var CompanyPaymentEventsResource = class {
    * Reprocess an event whose automatic invoicing didn't complete, applying the NIF's
    * **current** configuration. Only retryable states qualify and the retry budget is
    * finite: otherwise `400`.
+   *
+   * @param eventId - Event UUID.
+   * @returns The event after the retry.
    */
   async retry(eventId) {
     const { data } = await this.client.POST(
@@ -857,7 +1446,10 @@ var CompanyPaymentEventsResource = class {
   }
   /**
    * Build a **draft** invoice from an event that couldn't be invoiced automatically,
-   * so you can review it before issuing. Returns the draft's id.
+   * so you can review it before issuing.
+   *
+   * @param eventId - Event UUID.
+   * @returns The draft's `invoice_id`.
    */
   async draft(eventId) {
     const { data } = await this.client.POST(
@@ -866,7 +1458,12 @@ var CompanyPaymentEventsResource = class {
     );
     return data.data;
   }
-  /** Mark an event as dealt with outside the automatic flow. */
+  /**
+   * Mark an event as dealt with outside the automatic flow.
+   *
+   * @param eventId - Event UUID.
+   * @returns The resolved event.
+   */
   async resolve(eventId) {
     const { data } = await this.client.POST(
       "/v1/companies/{company_id}/payment-connections/{connection_id}/events/{event_id}/resolve",
@@ -874,7 +1471,12 @@ var CompanyPaymentEventsResource = class {
     );
     return data.data;
   }
-  /** Discard an event so it stops asking for attention. Reversible with {@link restore}. */
+  /**
+   * Discard an event so it stops asking for attention. Reversible with {@link restore}.
+   *
+   * @param eventId - Event UUID.
+   * @returns The discarded event.
+   */
   async discard(eventId) {
     const { data } = await this.client.POST(
       "/v1/companies/{company_id}/payment-connections/{connection_id}/events/{event_id}/discard",
@@ -882,7 +1484,12 @@ var CompanyPaymentEventsResource = class {
     );
     return data.data;
   }
-  /** Bring a discarded event back into the list. */
+  /**
+   * Bring a discarded event back into the list.
+   *
+   * @param eventId - Event UUID.
+   * @returns The restored event.
+   */
   async restore(eventId) {
     const { data } = await this.client.POST(
       "/v1/companies/{company_id}/payment-connections/{connection_id}/events/{event_id}/restore",
@@ -892,6 +1499,44 @@ var CompanyPaymentEventsResource = class {
   }
 };
 
+// src/resources/invoice-create-once.ts
+var EXTERNAL_REF_UNIQUE_INVOICE_TYPES = ["STANDARD", "SIMPLIFIED"];
+var MISSING_EXTERNAL_REF_MESSAGE = "invoices.createOnce requires a non-empty `external_ref`: it is the key that makes the call safe to repeat.";
+var UNSUPPORTED_TYPE_MESSAGE = "invoices.createOnce only creates STANDARD or SIMPLIFIED invoices: the API keeps `external_ref` unique for those types only.";
+function holdsTheReference(invoice) {
+  return EXTERNAL_REF_UNIQUE_INVOICE_TYPES.includes(invoice.type);
+}
+async function findHolder(operations, externalRef) {
+  const invoices = await operations.listByExternalRef(externalRef);
+  return invoices.find(holdsTheReference);
+}
+function isDuplicateReference(error) {
+  return error instanceof BeeLConflictError && error.apiCode === BeeLErrorCodes.INVOICE_DUPLICATE_EXTERNAL_REFERENCE;
+}
+function isUnknownOutcome(error) {
+  if (!(error instanceof BeeLApiError)) return true;
+  if (isServerErrorStatus(error.statusCode)) return true;
+  return error instanceof BeeLConflictError && error.apiCode === BeeLErrorCodes.IDEMPOTENCY_KEY_PROCESSING;
+}
+async function createInvoiceOnce(operations, body, params) {
+  if (typeof body.external_ref !== "string" || body.external_ref.trim() === "") {
+    throw new TypeError(MISSING_EXTERNAL_REF_MESSAGE);
+  }
+  if (!EXTERNAL_REF_UNIQUE_INVOICE_TYPES.includes(body.type)) {
+    throw new TypeError(UNSUPPORTED_TYPE_MESSAGE);
+  }
+  const existing = await findHolder(operations, body.external_ref);
+  if (existing) return existing;
+  try {
+    return await operations.create(body, params);
+  } catch (error) {
+    if (!isDuplicateReference(error) && !isUnknownOutcome(error)) throw error;
+    const holder = await findHolder(operations, body.external_ref).catch(() => void 0);
+    if (holder) return holder;
+    throw error;
+  }
+}
+
 // src/resources/company.ts
 var CompanyScope = class {
   constructor(client, companyId) {
@@ -909,14 +1554,24 @@ var CompanyScope = class {
   path() {
     return { company_id: this.companyId };
   }
-  /** Get the company. */
+  /**
+   * Get the company: its fiscal identity, address and settings.
+   *
+   * @param params - Optional query of `getCompanyById` (e.g. `include`).
+   * @returns The company.
+   */
   async get(params) {
     const { data } = await this.client.GET("/v1/companies/{company_id}", {
       params: { path: this.path(), query: params }
     });
     return data.data;
   }
-  /** Update company data. */
+  /**
+   * Update the company's data. Only the fields present in `body` change.
+   *
+   * @param body - Fields to change.
+   * @returns The updated company.
+   */
   async update(body) {
     const { data } = await this.client.PATCH("/v1/companies/{company_id}", {
       params: { path: this.path() },
@@ -924,18 +1579,30 @@ var CompanyScope = class {
     });
     return data.data;
   }
-  /** Delete the company. */
+  /**
+   * Remove the company from its account. Blocked for the primary NIF, a NIF active in Live,
+   * or one holding Live invoices.
+   */
   async delete() {
     await this.client.DELETE("/v1/companies/{company_id}", { params: { path: this.path() } });
   }
-  /** Fiscal summary (VAT/IRPF aggregates) for the company. */
+  /**
+   * Fiscal summary of the company for a period: taxable base, VAT and IRPF aggregates.
+   *
+   * @param params - `start_date` and `end_date` (both or neither; default: the current month).
+   * @returns The aggregates of the period.
+   */
   async fiscalSummary(params) {
     const { data } = await this.client.GET("/v1/companies/{company_id}/fiscal-summary", {
       params: { path: this.path(), query: params }
     });
     return data.data;
   }
-  /** Whether the company can already issue invoices, and what is missing if not. */
+  /**
+   * Whether the company can issue invoices now, and what blocks it if not.
+   *
+   * @returns `ready` plus the list of `blockers`.
+   */
   async issuingReadiness() {
     const { data } = await this.client.GET("/v1/companies/{company_id}/issuing-readiness", {
       params: { path: this.path() }
@@ -950,10 +1617,16 @@ var CompanyInvoicesResource = class {
     this.schedule = new CompanyInvoiceScheduleResource(client, companyId);
   }
   /**
-   * Derive a new invoice from an existing one — the canonical form of `duplicate`.
+   * Derive a new draft invoice from an existing one — the canonical form of `duplicate`.
+   * The source invoice is not modified.
+   *
+   * @param body - `from_invoice_id`, and optionally the `series_id` of the copy.
+   * @param options - Per-call `idempotencyKey`, `signal` and `timeoutMs`.
+   * @returns The new draft invoice.
    */
-  async derive(body) {
+  async derive(body, options) {
     const { data } = await this.client.POST("/v1/companies/{company_id}/invoices/derivations", {
+      ...toRequestInit(options),
       params: { path: { company_id: this.companyId } },
       body
     });
@@ -962,88 +1635,309 @@ var CompanyInvoicesResource = class {
   path(rest) {
     return { company_id: this.companyId, ...rest };
   }
-  async list(params) {
+  /**
+   * List the company's invoices, paginated, with filters: status, type, customer, dates,
+   * `external_ref` (exact match), VeriFactu status and more.
+   *
+   * @param params - Filters and pagination (`page`, `limit`).
+   * @param options - Per-call `idempotencyKey`, `signal` and `timeoutMs`.
+   * @returns The page of `invoices` and its `pagination`.
+   *
+   * @example
+   * ```typescript
+   * const { invoices } = await company.invoices.list({ external_ref: 'ORD-2026-0042' });
+   * ```
+   */
+  async list(params, options) {
     const { data } = await this.client.GET("/v1/companies/{company_id}/invoices", {
+      ...toRequestInit(options),
       params: { path: this.path(), query: params }
     });
     return data.data;
   }
-  async create(body, params) {
+  /**
+   * Create an invoice: a `DRAFT` by default, or numbered and issued in the same call with
+   * `options.issue_directly: true`. `CORRECTIVE` is not accepted here: use
+   * {@link createCorrective}.
+   *
+   * One call sends one `Idempotency-Key`, reused by the client's automatic retries, so
+   * those never duplicate the invoice. A second call is a new operation: to repeat a create
+   * whose outcome you do not know, use {@link createOnce}.
+   *
+   * @param body - Type, recipient and lines; `external_ref` to tie it to your order.
+   * @param params - `wait_for_pdf`, when issuing directly.
+   * @param options - Per-call `idempotencyKey`, `signal` and `timeoutMs`.
+   * @returns The created invoice. With VeriFactu, `verifactu.submission_status` starts `PENDING`.
+   *
+   * @example
+   * ```typescript
+   * const invoice = await company.invoices.create({
+   *   type: 'STANDARD',
+   *   recipient: { customer_id: 'customer-uuid' },
+   *   lines: [{
+   *     description: 'Consulting', quantity: 1, unit_price: 100,
+   *     main_tax: { type: 'IVA', percentage: 21, regime_key: '01' },
+   *   }],
+   *   external_ref: 'ORD-2026-0042',
+   * });
+   * ```
+   */
+  async create(body, params, options) {
     const { data } = await this.client.POST("/v1/companies/{company_id}/invoices", {
+      ...toRequestInit(options),
       params: { path: this.path(), query: params },
       body
     });
     return data.data;
   }
-  async get(invoiceId) {
+  /**
+   * Create a standard or simplified invoice once per `external_ref`, safe to call again
+   * after any failure. It looks the reference up first and returns the invoice that already
+   * holds it; otherwise it creates one. If the create answers
+   * `409 INVOICE_DUPLICATE_EXTERNAL_REFERENCE`, or its outcome is unknown (network error,
+   * `5xx`), it looks the reference up again and returns the invoice it finds.
+   *
+   * The returned invoice may be one created earlier, in any status (`VOIDED` included):
+   * compare its fields if that matters to you.
+   *
+   * @param body - A `CreateInvoiceRequest` with `type` `STANDARD` or `SIMPLIFIED` and a
+   *   non-empty `external_ref`.
+   * @param params - `wait_for_pdf`, when issuing directly.
+   * @param options - `idempotencyKey` for the create; `signal` and `timeoutMs` for the whole
+   *   sequence of calls.
+   * @returns The one invoice that holds `body.external_ref`.
+   * @throws {TypeError} Before any request, when `external_ref` is empty or `type` is not
+   *   `STANDARD`/`SIMPLIFIED`.
+   * @throws {BeeLApiError} The create's error when no invoice holds the reference
+   *   afterwards — nothing was created, so calling again is safe.
+   *
+   * @example
+   * ```typescript
+   * const invoice = await company.invoices.createOnce({
+   *   type: 'STANDARD',
+   *   external_ref: order.id,
+   *   recipient: { customer_id: order.customerId },
+   *   lines: [{ description: 'Order', quantity: 1, unit_price: 100,
+   *     main_tax: { type: 'IVA', percentage: 21, regime_key: '01' } }],
+   *   options: { issue_directly: true },
+   * });
+   * ```
+   */
+  async createOnce(body, params, options) {
+    const { signal } = toRequestInit({ signal: options?.signal, timeoutMs: options?.timeoutMs });
+    return createInvoiceOnce(
+      {
+        listByExternalRef: async (externalRef) => (await this.list({ external_ref: externalRef }, { signal })).invoices,
+        create: (request, query) => this.create(request, query, { signal, idempotencyKey: options?.idempotencyKey })
+      },
+      body,
+      params
+    );
+  }
+  /**
+   * Get one invoice, including its `status` and its `verifactu` block
+   * (`submission_status`, `qr_url`, `error_code`…).
+   *
+   * @param invoiceId - Invoice UUID.
+   * @param options - Per-call `idempotencyKey`, `signal` and `timeoutMs`.
+   * @returns The invoice.
+   */
+  async get(invoiceId, options) {
     const { data } = await this.client.GET("/v1/companies/{company_id}/invoices/{invoice_id}", {
+      ...toRequestInit(options),
       params: { path: this.path({ invoice_id: invoiceId }) }
     });
     return data.data;
   }
-  /** Update a draft invoice. */
-  async update(invoiceId, body) {
+  /**
+   * Update a `DRAFT` or `SCHEDULED` invoice (or an `ACTIVE` proforma). Only the fields
+   * present in `body` change; an issued invoice is amended with a corrective instead.
+   *
+   * @param invoiceId - Invoice UUID.
+   * @param body - Fields to change.
+   * @param options - Per-call `idempotencyKey`, `signal` and `timeoutMs`.
+   * @returns The updated invoice.
+   */
+  async update(invoiceId, body, options) {
     const { data } = await this.client.PATCH("/v1/companies/{company_id}/invoices/{invoice_id}", {
+      ...toRequestInit(options),
       params: { path: this.path({ invoice_id: invoiceId }) },
       body
     });
     return data.data;
   }
-  /** Delete a draft invoice. */
-  async delete(invoiceId) {
+  /**
+   * Delete a draft invoice. Deleting frees its `external_ref` for a new invoice.
+   *
+   * @param invoiceId - Invoice UUID.
+   * @param options - Per-call `idempotencyKey`, `signal` and `timeoutMs`.
+   */
+  async delete(invoiceId, options) {
     await this.client.DELETE("/v1/companies/{company_id}/invoices/{invoice_id}", {
+      ...toRequestInit(options),
       params: { path: this.path({ invoice_id: invoiceId }) }
     });
   }
-  /** Issue a draft invoice (assigns number, submits to VeriFactu when configured). */
-  async issue(invoiceId, params) {
+  /**
+   * Issue a draft: assigns its definitive number and makes it immutable. PDF generation and
+   * the VeriFactu submission happen after the response.
+   *
+   * @param invoiceId - UUID of the draft.
+   * @param params - `wait_for_pdf: true` to wait for the PDF before answering.
+   * @param options - Per-call `idempotencyKey`, `signal` and `timeoutMs`.
+   * @returns The issued invoice.
+   */
+  async issue(invoiceId, params, options) {
     const { data } = await this.client.POST("/v1/companies/{company_id}/invoices/{invoice_id}/issue", {
+      ...toRequestInit(options),
       params: { path: this.path({ invoice_id: invoiceId }), query: params }
     });
     return data.data;
   }
-  /** Void an issued invoice. */
-  async void(invoiceId, body) {
+  /**
+   * Void an invoice issued by mistake. The document is kept and its number never reused. If
+   * the operation did happen but the invoice is wrong, use {@link createCorrective}.
+   *
+   * @param invoiceId - Invoice UUID.
+   * @param body - `reason`; `issued_in_error: true` is required once it was sent or paid.
+   * @param options - Per-call `idempotencyKey`, `signal` and `timeoutMs`.
+   * @returns The voided invoice.
+   */
+  async void(invoiceId, body, options) {
     const { data } = await this.client.POST("/v1/companies/{company_id}/invoices/{invoice_id}/void", {
+      ...toRequestInit(options),
       params: { path: this.path({ invoice_id: invoiceId }) },
       body
     });
     return data.data;
   }
-  /** Create a corrective (rectificativa) for an issued invoice. */
-  async createCorrective(invoiceId, body) {
+  /**
+   * Create a corrective invoice (rectificativa) for an issued invoice.
+   *
+   * @param invoiceId - UUID of the issued invoice to correct.
+   * @param body - `rectification_type` (`TOTAL`/`PARTIAL`), `rectification_code` (`R1`–`R5`),
+   *   `reason` and, for `PARTIAL`, the correcting `lines`.
+   * @param options - Per-call `idempotencyKey`, `signal` and `timeoutMs`.
+   * @returns The corrective invoice.
+   *
+   * @example
+   * ```typescript
+   * const corrective = await company.invoices.createCorrective('invoice-uuid', {
+   *   rectification_type: 'PARTIAL',
+   *   rectification_code: 'R1',
+   *   reason: 'Discount agreed with the customer after the sale',
+   *   lines: [{ description: 'Discount', quantity: -1, unit_price: 10,
+   *     main_tax: { type: 'IVA', percentage: 21, regime_key: '01' } }],
+   * });
+   * ```
+   */
+  async createCorrective(invoiceId, body, options) {
     const { data } = await this.client.POST("/v1/companies/{company_id}/invoices/{invoice_id}/corrective", {
+      ...toRequestInit(options),
       params: { path: this.path({ invoice_id: invoiceId }) },
       body
     });
     return data.data;
   }
-  /** Convert a proforma into an invoice. */
-  async convertToInvoice(invoiceId, body) {
+  /**
+   * Convert a proforma into an invoice.
+   *
+   * @param invoiceId - UUID of the proforma.
+   * @param body - Optional overrides for the new invoice.
+   * @param options - Per-call `idempotencyKey`, `signal` and `timeoutMs`.
+   * @returns The new invoice.
+   */
+  async convertToInvoice(invoiceId, body, options) {
     const { data } = await this.client.POST("/v1/companies/{company_id}/invoices/{invoice_id}/convert-to-invoice", {
+      ...toRequestInit(options),
       params: { path: this.path({ invoice_id: invoiceId }) },
       body
     });
     return data.data;
   }
-  /** Update payment status (e.g. mark as paid). */
-  async setStatus(invoiceId, body) {
+  /**
+   * Issue a full invoice in exchange for one or more issued simplified invoices, when the
+   * customer asks for an invoice with their details. It is not a corrective: the simplified
+   * invoices become `VOIDED` with `void_cause: 'EXCHANGED'`, and the new `STANDARD` invoice
+   * lists them in `replaced_invoice_ids`.
+   *
+   * @param body - `simplified_invoice_ids` and the identified `recipient`.
+   * @param options - Per-call `idempotencyKey`, `signal` and `timeoutMs`.
+   * @returns The new standard invoice.
+   *
+   * @example
+   * ```typescript
+   * const invoice = await company.invoices.createSimplifiedExchange({
+   *   simplified_invoice_ids: ['simplified-uuid'],
+   *   recipient: { customer_id: 'customer-uuid' },
+   * });
+   * ```
+   */
+  async createSimplifiedExchange(body, options) {
+    const { data } = await this.client.POST("/v1/companies/{company_id}/invoices/simplified-exchanges", {
+      ...toRequestInit(options),
+      params: { path: this.path() },
+      body
+    });
+    return data.data;
+  }
+  /**
+   * The VeriFactu records of an invoice, oldest first: its registration and, if it was
+   * voided, its cancellation. An invoice never submitted answers with an empty list.
+   *
+   * @param invoiceId - Invoice UUID.
+   * @param options - Per-call `idempotencyKey`, `signal` and `timeoutMs`.
+   * @returns The records (`data.records` of the response), each with its own `submission_status`.
+   */
+  async verifactuRecords(invoiceId, options) {
+    const { data } = await this.client.GET("/v1/companies/{company_id}/invoices/{invoice_id}/verifactu-records", {
+      ...toRequestInit(options),
+      params: { path: this.path({ invoice_id: invoiceId }) }
+    });
+    return data.data.records;
+  }
+  /**
+   * Set the commercial status: `PAID` (from `ISSUED`, `SENT`, `OVERDUE`), `SENT` (from
+   * `ISSUED`) or back to `ISSUED` (from `SENT`). Issuing and voiding have their own methods.
+   *
+   * @param invoiceId - Invoice UUID.
+   * @param body - Target `status` and, for `PAID`, the payment details.
+   * @param options - Per-call `idempotencyKey`, `signal` and `timeoutMs`.
+   * @returns The updated invoice.
+   */
+  async setStatus(invoiceId, body, options) {
     const { data } = await this.client.PUT("/v1/companies/{company_id}/invoices/{invoice_id}/status", {
+      ...toRequestInit(options),
       params: { path: this.path({ invoice_id: invoiceId }) },
       body
     });
     return data.data;
   }
-  /** Get PDF metadata and download URL. */
-  async getPdf(invoiceId) {
+  /**
+   * Get a short-lived download URL for the invoice PDF.
+   *
+   * @param invoiceId - Invoice UUID.
+   * @param options - Per-call `idempotencyKey`, `signal` and `timeoutMs`.
+   * @returns `download_url`, `expires_in_seconds` and `file_name`.
+   */
+  async getPdf(invoiceId, options) {
     const { data } = await this.client.GET("/v1/companies/{company_id}/invoices/{invoice_id}/pdf", {
+      ...toRequestInit(options),
       params: { path: this.path({ invoice_id: invoiceId }) }
     });
     return data.data;
   }
-  /** Send the invoice by email to the customer. */
-  async send(invoiceId, body) {
+  /**
+   * Send the invoice by email with its PDF. Without recipients, the customer's addresses are used.
+   *
+   * @param invoiceId - Invoice UUID.
+   * @param body - Optional recipients, subject and message.
+   * @param options - Per-call `idempotencyKey`, `signal` and `timeoutMs`.
+   * @returns The delivery record.
+   */
+  async send(invoiceId, body, options) {
     const { data } = await this.client.POST("/v1/companies/{company_id}/invoices/{invoice_id}/send", {
+      ...toRequestInit(options),
       params: { path: this.path({ invoice_id: invoiceId }) },
       body
     });
@@ -1055,6 +1949,12 @@ var CompanyInvoiceScheduleResource = class {
     this.client = client;
     this.companyId = companyId;
   }
+  /**
+   * Get the schedule of an invoice.
+   *
+   * @param invoiceId - Invoice UUID.
+   * @returns `scheduled_for` and `generation_mode`.
+   */
   async get(invoiceId) {
     const { data } = await this.client.GET(
       "/v1/companies/{company_id}/invoices/{invoice_id}/schedule",
@@ -1065,6 +1965,10 @@ var CompanyInvoiceScheduleResource = class {
   /**
    * Set or move the schedule. One `PUT` replaces the three legacy calls
    * (`schedule`, `reschedule`, `unschedule`): setting it again moves it.
+   *
+   * @param invoiceId - UUID of a draft invoice.
+   * @param body - `scheduled_for` date and what to do then.
+   * @returns The scheduled invoice.
    */
   async set(invoiceId, body) {
     const { data } = await this.client.PUT(
@@ -1073,7 +1977,12 @@ var CompanyInvoiceScheduleResource = class {
     );
     return data.data;
   }
-  /** Clear the schedule — the canonical form of `unschedule`. */
+  /**
+   * Clear the schedule, returning the invoice to a plain draft — the canonical form of
+   * `unschedule`. Idempotent.
+   *
+   * @param invoiceId - Invoice UUID.
+   */
   async clear(invoiceId) {
     await this.client.DELETE("/v1/companies/{company_id}/invoices/{invoice_id}/schedule", {
       params: { path: { company_id: this.companyId, invoice_id: invoiceId } }
@@ -1085,12 +1994,24 @@ var CompanyCustomersResource = class {
     this.client = client;
     this.companyId = companyId;
   }
+  /**
+   * List the company's customers, paginated and searchable.
+   *
+   * @param params - Filters and pagination.
+   * @returns The page of `customers` and its `pagination`.
+   */
   async list(params) {
     const { data } = await this.client.GET("/v1/companies/{company_id}/customers", {
       params: { path: { company_id: this.companyId }, query: params }
     });
     return data.data;
   }
+  /**
+   * Create a customer.
+   *
+   * @param body - Legal name, NIF (or alternative id) and address.
+   * @returns The created customer.
+   */
   async create(body) {
     const { data } = await this.client.POST("/v1/companies/{company_id}/customers", {
       params: { path: { company_id: this.companyId } },
@@ -1098,6 +2019,12 @@ var CompanyCustomersResource = class {
     });
     return data.data;
   }
+  /**
+   * Create several customers in one call.
+   *
+   * @param body - The customers, and whether it is a dry run.
+   * @returns Per-customer results and totals.
+   */
   async createBulk(body) {
     const { data } = await this.client.POST("/v1/companies/{company_id}/customers/bulk", {
       params: { path: { company_id: this.companyId } },
@@ -1105,12 +2032,25 @@ var CompanyCustomersResource = class {
     });
     return data.data;
   }
+  /**
+   * Get one customer.
+   *
+   * @param customerId - Customer UUID.
+   * @returns The customer.
+   */
   async get(customerId) {
     const { data } = await this.client.GET("/v1/companies/{company_id}/customers/{customer_id}", {
       params: { path: { company_id: this.companyId, customer_id: customerId } }
     });
     return data.data;
   }
+  /**
+   * Update a customer. Only the fields present in `body` change.
+   *
+   * @param customerId - Customer UUID.
+   * @param body - Fields to change.
+   * @returns The updated customer.
+   */
   async update(customerId, body) {
     const { data } = await this.client.PATCH("/v1/companies/{company_id}/customers/{customer_id}", {
       params: { path: { company_id: this.companyId, customer_id: customerId } },
@@ -1118,6 +2058,12 @@ var CompanyCustomersResource = class {
     });
     return data.data;
   }
+  /**
+   * Delete a customer that has no invoices. Its NIF (or alternative id) is released for a
+   * new customer.
+   *
+   * @param customerId - Customer UUID.
+   */
   async delete(customerId) {
     await this.client.DELETE("/v1/companies/{company_id}/customers/{customer_id}", {
       params: { path: { company_id: this.companyId, customer_id: customerId } }
@@ -1129,12 +2075,24 @@ var CompanyProductsResource = class {
     this.client = client;
     this.companyId = companyId;
   }
+  /**
+   * List the company's products, paginated and searchable.
+   *
+   * @param params - Filters and pagination.
+   * @returns The page of `products` and its `pagination`.
+   */
   async list(params) {
     const { data } = await this.client.GET("/v1/companies/{company_id}/products", {
       params: { path: { company_id: this.companyId }, query: params }
     });
     return data.data;
   }
+  /**
+   * Create a product or service.
+   *
+   * @param body - Name, category, price and main tax.
+   * @returns The created product.
+   */
   async create(body) {
     const { data } = await this.client.POST("/v1/companies/{company_id}/products", {
       params: { path: { company_id: this.companyId } },
@@ -1142,12 +2100,25 @@ var CompanyProductsResource = class {
     });
     return data.data;
   }
+  /**
+   * Get one product.
+   *
+   * @param productId - Product UUID.
+   * @returns The product.
+   */
   async get(productId) {
     const { data } = await this.client.GET("/v1/companies/{company_id}/products/{product_id}", {
       params: { path: { company_id: this.companyId, product_id: productId } }
     });
     return data.data;
   }
+  /**
+   * Update a product. Only the fields present in `body` change.
+   *
+   * @param productId - Product UUID.
+   * @param body - Fields to change.
+   * @returns The updated product.
+   */
   async update(productId, body) {
     const { data } = await this.client.PATCH("/v1/companies/{company_id}/products/{product_id}", {
       params: { path: { company_id: this.companyId, product_id: productId } },
@@ -1155,6 +2126,11 @@ var CompanyProductsResource = class {
     });
     return data.data;
   }
+  /**
+   * Delete a product from the catalog. Existing invoice lines are unaffected.
+   *
+   * @param productId - Product UUID.
+   */
   async delete(productId) {
     await this.client.DELETE("/v1/companies/{company_id}/products/{product_id}", {
       params: { path: { company_id: this.companyId, product_id: productId } }
@@ -1166,12 +2142,24 @@ var CompanySeriesResource = class {
     this.client = client;
     this.companyId = companyId;
   }
+  /**
+   * List the company's series.
+   *
+   * @param params - Filters; `page`/`limit` to paginate.
+   * @returns The `series`, and `pagination` when you paginated.
+   */
   async list(params) {
     const { data } = await this.client.GET("/v1/companies/{company_id}/series", {
       params: { path: { company_id: this.companyId }, query: params }
     });
     return data.data;
   }
+  /**
+   * Create a series.
+   *
+   * @param body - Code, name, format and the `document_type` it numbers.
+   * @returns The created series.
+   */
   async create(body) {
     const { data } = await this.client.POST("/v1/companies/{company_id}/series", {
       params: { path: { company_id: this.companyId } },
@@ -1179,6 +2167,13 @@ var CompanySeriesResource = class {
     });
     return data.data;
   }
+  /**
+   * Update a series. Only the fields present in `body` change.
+   *
+   * @param seriesId - Series UUID.
+   * @param body - Fields to change.
+   * @returns The updated series.
+   */
   async update(seriesId, body) {
     const { data } = await this.client.PATCH("/v1/companies/{company_id}/series/{series_id}", {
       params: { path: { company_id: this.companyId, series_id: seriesId } },
@@ -1186,26 +2181,45 @@ var CompanySeriesResource = class {
     });
     return data.data;
   }
+  /**
+   * Delete (soft-delete) a series. Its code stays taken, since issued invoices carry it.
+   *
+   * @param seriesId - Series UUID.
+   */
   async delete(seriesId) {
     await this.client.DELETE("/v1/companies/{company_id}/series/{series_id}", {
       params: { path: { company_id: this.companyId, series_id: seriesId } }
     });
   }
-  /** Current default series per invoice type. */
+  /**
+   * The current default series per document type.
+   *
+   * @returns One entry per document type, saying whether a default exists.
+   */
   async getDefaults() {
     const { data } = await this.client.GET("/v1/companies/{company_id}/series/defaults", {
       params: { path: { company_id: this.companyId } }
     });
     return data.data;
   }
-  /** Ensure the three typed default series exist (idempotent seeding). */
+  /**
+   * Ensure a default series exists per document type, creating the missing ones.
+   * Idempotent.
+   *
+   * @returns The default series.
+   */
   async ensureDefaults() {
     const { data } = await this.client.PUT("/v1/companies/{company_id}/series/defaults", {
       params: { path: { company_id: this.companyId } }
     });
     return data.data;
   }
-  /** Mark a series as the default for its invoice type. */
+  /**
+   * Mark a series as the default for its document type.
+   *
+   * @param seriesId - Series UUID.
+   * @returns The series.
+   */
   async setDefault(seriesId) {
     const { data } = await this.client.PUT("/v1/companies/{company_id}/series/{series_id}/default", {
       params: { path: { company_id: this.companyId, series_id: seriesId } }
@@ -1221,12 +2235,24 @@ var CompanyRecurringInvoicesResource = class {
   path(rest) {
     return { company_id: this.companyId, ...rest };
   }
+  /**
+   * List the recurring invoices.
+   *
+   * @param params - Filters and pagination.
+   * @returns The page of `recurring_invoices` and its `pagination`.
+   */
   async list(params) {
     const { data } = await this.client.GET("/v1/companies/{company_id}/recurring-invoices", {
       params: { path: this.path(), query: params }
     });
     return data.data;
   }
+  /**
+   * Create a recurring invoice template.
+   *
+   * @param body - Frequency, schedule, recipient and lines.
+   * @returns The recurring invoice.
+   */
   async create(body) {
     const { data } = await this.client.POST("/v1/companies/{company_id}/recurring-invoices", {
       params: { path: this.path() },
@@ -1234,12 +2260,25 @@ var CompanyRecurringInvoicesResource = class {
     });
     return data.data;
   }
+  /**
+   * Get one recurring invoice.
+   *
+   * @param recurringInvoiceId - Recurring invoice UUID.
+   * @returns The recurring invoice.
+   */
   async get(recurringInvoiceId) {
     const { data } = await this.client.GET("/v1/companies/{company_id}/recurring-invoices/{recurring_invoice_id}", {
       params: { path: this.path({ recurring_invoice_id: recurringInvoiceId }) }
     });
     return data.data;
   }
+  /**
+   * Update a recurring invoice. Only the fields present in `body` change.
+   *
+   * @param recurringInvoiceId - Recurring invoice UUID.
+   * @param body - Fields to change.
+   * @returns The updated recurring invoice.
+   */
   async update(recurringInvoiceId, body) {
     const { data } = await this.client.PATCH("/v1/companies/{company_id}/recurring-invoices/{recurring_invoice_id}", {
       params: { path: this.path({ recurring_invoice_id: recurringInvoiceId }) },
@@ -1247,12 +2286,24 @@ var CompanyRecurringInvoicesResource = class {
     });
     return data.data;
   }
+  /**
+   * Delete a recurring invoice and cancel its pending generations. Invoices it already
+   * generated are kept.
+   *
+   * @param recurringInvoiceId - Recurring invoice UUID.
+   */
   async delete(recurringInvoiceId) {
     await this.client.DELETE("/v1/companies/{company_id}/recurring-invoices/{recurring_invoice_id}", {
       params: { path: this.path({ recurring_invoice_id: recurringInvoiceId }) }
     });
   }
-  /** Pause or resume the schedule. */
+  /**
+   * Pause, resume or end the template.
+   *
+   * @param recurringInvoiceId - Recurring invoice UUID.
+   * @param body - Target `status` (e.g. `PAUSED`, `ACTIVE`).
+   * @returns The updated recurring invoice.
+   */
   async setStatus(recurringInvoiceId, body) {
     const { data } = await this.client.PUT("/v1/companies/{company_id}/recurring-invoices/{recurring_invoice_id}/status", {
       params: { path: this.path({ recurring_invoice_id: recurringInvoiceId }) },
@@ -1260,26 +2311,49 @@ var CompanyRecurringInvoicesResource = class {
     });
     return data.data;
   }
-  /** Skip the next scheduled occurrence. */
+  /**
+   * Skip the next scheduled occurrence.
+   *
+   * @param recurringInvoiceId - Recurring invoice UUID.
+   * @returns The recurring invoice with its next date moved.
+   */
   async skip(recurringInvoiceId) {
     const { data } = await this.client.POST("/v1/companies/{company_id}/recurring-invoices/{recurring_invoice_id}/skip", {
       params: { path: this.path({ recurring_invoice_id: recurringInvoiceId }) }
     });
     return data.data;
   }
-  /** Generate the next invoice now instead of waiting for the schedule. */
+  /**
+   * Generate the next invoice now instead of waiting for the schedule.
+   *
+   * @param recurringInvoiceId - Recurring invoice UUID.
+   * @returns The generated `invoice_id` and the `next_generation` date.
+   */
   async generateNow(recurringInvoiceId) {
     const { data } = await this.client.POST("/v1/companies/{company_id}/recurring-invoices/{recurring_invoice_id}/generate", {
       params: { path: this.path({ recurring_invoice_id: recurringInvoiceId }) }
     });
     return data.data;
   }
+  /**
+   * Preview the next invoice the template will generate.
+   *
+   * @param recurringInvoiceId - Recurring invoice UUID.
+   * @returns The invoice as it would be generated.
+   */
   async nextOccurrence(recurringInvoiceId) {
     const { data } = await this.client.GET("/v1/companies/{company_id}/recurring-invoices/{recurring_invoice_id}/next-occurrence", {
       params: { path: this.path({ recurring_invoice_id: recurringInvoiceId }) }
     });
     return data.data;
   }
+  /**
+   * The generation history of the template: generated, skipped and failed occurrences.
+   *
+   * @param recurringInvoiceId - Recurring invoice UUID.
+   * @param params - Pagination.
+   * @returns The `history` entries.
+   */
   async history(recurringInvoiceId, params) {
     const { data } = await this.client.GET("/v1/companies/{company_id}/recurring-invoices/{recurring_invoice_id}/history", {
       params: { path: this.path({ recurring_invoice_id: recurringInvoiceId }), query: params }
@@ -1292,13 +2366,23 @@ var CompanyTaxConfigurationResource = class {
     this.client = client;
     this.companyId = companyId;
   }
+  /**
+   * Get the tax configuration.
+   *
+   * @returns The company's tax defaults.
+   */
   async get() {
     const { data } = await this.client.GET("/v1/companies/{company_id}/tax-configuration", {
       params: { path: { company_id: this.companyId } }
     });
     return data.data;
   }
-  /** Replaces the whole state — this is a `PUT`, not a merge. */
+  /**
+   * Replace the tax configuration — this is a `PUT`, not a merge: send the whole state.
+   *
+   * @param body - The complete tax configuration.
+   * @returns The stored configuration.
+   */
   async update(body) {
     const { data } = await this.client.PUT("/v1/companies/{company_id}/tax-configuration", {
       params: { path: { company_id: this.companyId } },
@@ -1312,13 +2396,23 @@ var CompanyVeriFactuConfigurationResource = class {
     this.client = client;
     this.companyId = companyId;
   }
+  /**
+   * Get the VeriFactu configuration of this NIF.
+   *
+   * @returns `enabled` and the server-resolved state of the NIF.
+   */
   async get() {
     const { data } = await this.client.GET("/v1/companies/{company_id}/verifactu-configuration", {
       params: { path: { company_id: this.companyId } }
     });
     return data.data;
   }
-  /** Flip VeriFactu for this NIF. `enabled` is the only field you can write. */
+  /**
+   * Turn VeriFactu on or off for this NIF. `enabled` is the only field you can write.
+   *
+   * @param body - `{ enabled }`.
+   * @returns The updated configuration.
+   */
   async update(body) {
     const { data } = await this.client.PUT("/v1/companies/{company_id}/verifactu-configuration", {
       params: { path: { company_id: this.companyId } },
@@ -1344,7 +2438,11 @@ var BeeL = class {
   }
   /**
    * Returns a facade scoped to one company (NIF) — the explicit multi-NIF surface.
-   * All operations address the company in the path, no session focus needed.
+   * All operations address the company in the path, no session focus needed. No request
+   * is made; get the ids from `beel.account(accountId).companies.list()`.
+   *
+   * @param companyId - Company UUID (not its NIF).
+   * @returns The company scope.
    *
    * @example
    * ```typescript
@@ -1356,8 +2454,12 @@ var BeeL = class {
     return new CompanyScope(this.raw, companyId);
   }
   /**
-   * Returns a facade scoped to one managed account — members, invitations,
-   * account webhooks, companies, usage. Symmetric with {@link company}.
+   * Returns a facade scoped to one account — companies, members, invitations, account
+   * webhooks, usage. Symmetric with {@link company}. No request is made; your own account
+   * id is `(await beel.catalogs.identity()).account_id`.
+   *
+   * @param accountId - Account UUID.
+   * @returns The account scope.
    *
    * @example
    * ```typescript
@@ -1374,6 +2476,10 @@ var BeeL = class {
    * @deprecated Relies on the deprecated session-focus PDF endpoint. Use
    * `beel.company(companyId).invoices.getPdf(invoiceId)` and fetch `download_url` instead.
    *
+   * @param invoiceId - Invoice UUID.
+   * @returns The PDF bytes and its file name.
+   * @throws {Error} When downloading the file fails.
+   *
    * @example
    * ```typescript
    * const { buffer, fileName } = await beel.downloadPdf('invoice-uuid');
@@ -1418,6 +2524,7 @@ var WebhookVerifier = class {
    * const verifier = new WebhookVerifier('your_secret');
    * const event = verifier.verify(rawBody, signature);
    * 
+   * if (event.test) return; // a "Send test" delivery carries a synthetic `data`
    * if (event.type === 'verifactu.status.updated') {
    *   console.log('Invoice:', event.data.invoice_number);
    *   console.log('Status:', event.data.new_status);
@@ -1541,6 +2648,24 @@ var InvoiceIssuedEvent;
   })(type = InvoiceIssuedEvent2.type || (InvoiceIssuedEvent2.type = {}));
 })(InvoiceIssuedEvent || (InvoiceIssuedEvent = {}));
 
+// src/generated-webhooks/models/InvoicePdfGeneratedEvent.ts
+var InvoicePdfGeneratedEvent;
+((InvoicePdfGeneratedEvent2) => {
+  let type;
+  ((type2) => {
+    type2["INVOICE_PDF_GENERATED"] = "invoice.pdf.generated";
+  })(type = InvoicePdfGeneratedEvent2.type || (InvoicePdfGeneratedEvent2.type = {}));
+})(InvoicePdfGeneratedEvent || (InvoicePdfGeneratedEvent = {}));
+
+// src/generated-webhooks/models/InvoiceScheduleFailedEvent.ts
+var InvoiceScheduleFailedEvent;
+((InvoiceScheduleFailedEvent2) => {
+  let type;
+  ((type2) => {
+    type2["INVOICE_SCHEDULE_FAILED"] = "invoice.schedule_failed";
+  })(type = InvoiceScheduleFailedEvent2.type || (InvoiceScheduleFailedEvent2.type = {}));
+})(InvoiceScheduleFailedEvent || (InvoiceScheduleFailedEvent = {}));
+
 // src/generated-webhooks/models/InvoiceVoidedEvent.ts
 var InvoiceVoidedEvent;
 ((InvoiceVoidedEvent2) => {
@@ -1591,8 +2716,10 @@ var WebhookEventType = /* @__PURE__ */ ((WebhookEventType2) => {
   WebhookEventType2["VERIFACTU_STATUS_UPDATED"] = "verifactu.status.updated";
   WebhookEventType2["INVOICE_ISSUED"] = "invoice.issued";
   WebhookEventType2["INVOICE_EMAIL_SENT"] = "invoice.email.sent";
+  WebhookEventType2["INVOICE_PDF_GENERATED"] = "invoice.pdf.generated";
   WebhookEventType2["INVOICE_VOIDED"] = "invoice.voided";
   WebhookEventType2["RECURRING_INVOICE_PAUSED"] = "recurring_invoice.paused";
+  WebhookEventType2["INVOICE_SCHEDULE_FAILED"] = "invoice.schedule_failed";
   WebhookEventType2["ACCOUNT_CLAIMED"] = "account.claimed";
   WebhookEventType2["COMPANY_CREATED"] = "company.created";
   WebhookEventType2["REPRESENTATION_SIGNED"] = "representation.signed";
@@ -1603,33 +2730,86 @@ var WebhookEventType = /* @__PURE__ */ ((WebhookEventType2) => {
 var CustomerBuilder = class _CustomerBuilder {
   constructor() {
   }
+  /**
+   * Start a new builder.
+   *
+   * @returns An empty customer builder.
+   */
   static create() {
     return new _CustomerBuilder();
   }
+  /**
+   * Legal name of the customer. Required.
+   *
+   * @param name - Legal name.
+   * @returns This builder.
+   */
   name(name) {
     this._name = name;
     return this;
   }
+  /**
+   * NIF/CIF of the customer. Required.
+   *
+   * @param nif - Spanish tax id.
+   * @returns This builder.
+   */
   nif(nif) {
     this._nif = nif;
     return this;
   }
+  /**
+   * Contact email.
+   *
+   * @param email - Email address.
+   * @returns This builder.
+   */
   email(email) {
     this._email = email;
     return this;
   }
+  /**
+   * Contact phone: 9 to 20 characters of digits, spaces, dashes, parentheses and a leading `+`.
+   *
+   * @param phone - Phone number.
+   * @returns This builder.
+   */
   phone(phone) {
     this._phone = phone;
     return this;
   }
+  /**
+   * Fiscal address. Required.
+   *
+   * @param street - Street name.
+   * @param number - Street number.
+   * @param postalCode - Postal code.
+   * @param city - City.
+   * @param province - Province.
+   * @param country - Country name.
+   * @param countryCode - ISO 3166-1 alpha-2 code. Default: `ES`.
+   * @returns This builder.
+   */
   address(street, number, postalCode, city, province, country, countryCode = "ES") {
     this._address = { street, number, postal_code: postalCode, city, province, country, country_code: countryCode };
     return this;
   }
+  /**
+   * Internal notes about the customer.
+   *
+   * @param notes - Free text.
+   * @returns This builder.
+   */
   notes(notes) {
     this._notes = notes;
     return this;
   }
+  /**
+   * Build the request body.
+   *
+   * @returns The `CreateCustomerRequest`.
+   * @throws {Error} When the name, NIF or address is missing.
+   */
   build() {
     if (!this._name || this._name.trim().length === 0) throw new Error("Legal name is required");
     if (!this._nif || this._nif.trim().length === 0) throw new Error("NIF/CIF is required");
@@ -1646,50 +2826,144 @@ var CustomerBuilder = class _CustomerBuilder {
 };
 
 // src/builders/invoice-builder.ts
+var NORMAL_LINE_TYPE = "NORMAL";
+var NO_DISCOUNT = 0;
+function toIsoDate(date) {
+  return date instanceof Date ? date.toISOString().split("T")[0] : date;
+}
 var InvoiceBuilder = class _InvoiceBuilder {
   constructor() {
     this._type = "STANDARD";
     this._lines = [];
   }
+  /**
+   * Start a new builder.
+   *
+   * @returns An empty `STANDARD` invoice builder.
+   */
   static create() {
     return new _InvoiceBuilder();
   }
+  /**
+   * Set the invoice type. Default: `STANDARD`.
+   *
+   * @param type - `STANDARD`, `SIMPLIFIED` or `PROFORMA` (correctives use `createCorrective`).
+   * @returns This builder.
+   */
   type(type) {
     this._type = type;
     return this;
   }
+  /**
+   * Invoice a registered customer.
+   *
+   * @param customerId - Customer UUID.
+   * @returns This builder.
+   */
   forCustomer(customerId) {
     this._customerId = customerId;
     return this;
   }
+  /**
+   * Date the operation took place, when it differs from the issue date.
+   *
+   * @param date - A `Date` or a `YYYY-MM-DD` string.
+   * @returns This builder.
+   */
   operationDate(date) {
-    this._operationDate = date instanceof Date ? date.toISOString().split("T")[0] : date;
+    this._operationDate = toIsoDate(date);
     return this;
   }
+  /**
+   * Payment due date.
+   *
+   * @param date - A `Date` or a `YYYY-MM-DD` string.
+   * @returns This builder.
+   */
   dueDate(date) {
-    this._dueDate = date instanceof Date ? date.toISOString().split("T")[0] : date;
+    this._dueDate = toIsoDate(date);
     return this;
   }
-  addLine(description, quantity, unitPrice, discountPercentage = 0) {
-    this._lines.push({ line_type: "NORMAL", description, quantity, unit_price: unitPrice, discount_percentage: discountPercentage });
+  /**
+   * Main tax applied to every line added with {@link addLine} after this call, unless the
+   * line passes its own.
+   *
+   * @param tax - For example `{ type: 'IVA', percentage: 21, regime_key: '01' }`.
+   * @returns This builder.
+   */
+  mainTax(tax) {
+    this._mainTax = tax;
+    return this;
+  }
+  /**
+   * Add a `NORMAL` line.
+   *
+   * @param description - What is invoiced.
+   * @param quantity - Units.
+   * @param unitPrice - Price per unit before taxes.
+   * @param discountPercentage - Discount, 0–100. Default: `0`.
+   * @param mainTax - Tax of this line; defaults to the one set with {@link mainTax}. The API
+   *   rejects a `NORMAL` line without one.
+   * @returns This builder.
+   */
+  addLine(description, quantity, unitPrice, discountPercentage = NO_DISCOUNT, mainTax) {
+    const tax = mainTax ?? this._mainTax;
+    this._lines.push({
+      line_type: NORMAL_LINE_TYPE,
+      description,
+      quantity,
+      unit_price: unitPrice,
+      discount_percentage: discountPercentage,
+      ...tax ? { main_tax: tax } : {}
+    });
     return this;
   }
+  /**
+   * Add a line exactly as given — any line type or pricing mode.
+   *
+   * @param line - A line of `CreateInvoiceRequest`.
+   * @returns This builder.
+   */
   addLineObject(line) {
     this._lines.push(line);
     return this;
   }
+  /**
+   * Notes printed on the invoice.
+   *
+   * @param notes - Free text.
+   * @returns This builder.
+   */
   notes(notes) {
     this._notes = notes;
     return this;
   }
+  /**
+   * Number the invoice in this series instead of the default one.
+   *
+   * @param id - Series UUID.
+   * @returns This builder.
+   */
   series(id) {
     this._seriesId = id;
     return this;
   }
+  /**
+   * Your own key/value pairs, filterable when listing.
+   *
+   * @param data - Metadata to store with the invoice.
+   * @returns This builder.
+   */
   metadata(data) {
     this._metadata = data;
     return this;
   }
+  /**
+   * Build the request body.
+   *
+   * @returns The `CreateInvoiceRequest`.
+   * @throws {Error} When there is no customer or no line.
+   */
   build() {
     if (!this._customerId) throw new Error("Customer ID is required");
     if (this._lines.length === 0) throw new Error("At least one invoice line is required");
@@ -1717,6 +2991,7 @@ export {
   BeeLApiError,
   BeeLAuthError,
   BeeLConflictError,
+  BeeLErrorCodes,
   BeeLNotFoundError,
   BeeLRateLimitError,
   BeeLValidationError,
@@ -1733,6 +3008,7 @@ export {
   CompanyTaxConfigurationResource,
   CompanyVeriFactuConfigurationResource,
   CustomerBuilder,
+  EXTERNAL_REF_UNIQUE_INVOICE_TYPES,
   InvoiceBuilder,
   VeriFactuSubmissionStatus,
   WebhookEventType,