@beel_es/sdk 2.0.0 → 2.1.0

package/dist/index.d.ts

@@ -7378,7 +7378,7 @@ interface components {
                  * @default 0
                  * @example 10
                  */
-                discount_percentage: number;
+                discount_percentage?: number;
                 /**
                  * @description Main tax of the line: regime (IVA/IGIC/IPSI/OTHER), percentage and regime key.
                  *
@@ -7464,7 +7464,7 @@ interface components {
                  *     (art. 78.Tres.3 LIVA). Requires `source_invoice_reference`.
                  * @default NORMAL
                  */
-                line_type: components["schemas"]["InvoiceLineType"];
+                line_type?: components["schemas"]["InvoiceLineType"];
                 /**
                  * @description Reference to the original invoice issued by the third party in the
                  *     client's name. Required when `line_type=SUPLIDO`.
@@ -7515,21 +7515,21 @@ interface components {
              *     If `false` (default), creates as **DRAFT** without number (editable, no PDF).
              * @default false
              */
-            issue_directly: boolean;
+            issue_directly?: boolean;
             /**
              * @description Only applies when `issue_directly` is `true`.
              *     If `true`, waits for PDF generation before returning the response (~1-3s).
              *     If `false` (default), PDF is generated asynchronously in the background.
              * @default false
              */
-            wait_for_pdf: boolean;
+            wait_for_pdf?: boolean;
             /**
              * @description Only applies when `issue_directly` is `true`.
              *     If `true`, sends the invoice by email with PDF attachment after issuing.
              *     The email is sent asynchronously after the invoice is issued.
              * @default false
              */
-            send_automatically: boolean;
+            send_automatically?: boolean;
             /**
              * @description Only applies when `send_automatically` is `true`. If `true`, the email sent after
              *     issuing also attaches a ZIP (`suplidos_<invoice-number>.zip`) with the PDFs of the
@@ -7544,7 +7544,7 @@ interface components {
              *     stored on the invoice.
              * @default false
              */
-            attach_source_invoices: boolean;
+            attach_source_invoices?: boolean;
             /**
              * @description Only applies when `send_automatically` is `true`.
              *     Overrides default email settings. If it names no recipients, the email goes to the
@@ -7765,12 +7765,12 @@ interface components {
             /** @description Custom message (optional, added before standard message) */
             message?: string;
             /** @default true */
-            attach_pdf: boolean;
+            attach_pdf?: boolean;
             /**
              * @description Attach a ZIP archive (`suplidos_<invoice-number>.zip`) containing the PDFs of the source invoices referenced by the invoice's SUPLIDO consolidation lines (`source_invoice_ids`). Each PDF inside the ZIP is named `<invoice-number>_<issuer-tax-id>.pdf`. Requires `attach_pdf: true` (the ZIP accompanies the invoice PDF). Access to sources owned by managed accounts is re-checked at send time with the same rules as issuing; the request fails with an actionable error — never a partial ZIP — if the invoice has no consolidation sources (`ATTACH_SOURCE_INVOICES_NO_SOURCES`), a source is not reachable (`ATTACH_SOURCE_INVOICE_UNAVAILABLE`), a source has no generated PDF (`ATTACH_SOURCE_PDF_MISSING`), or the ZIP exceeds the size limit (`ATTACH_SOURCE_ZIP_TOO_LARGE`).
              * @default false
              */
-            attach_source_invoices: boolean;
+            attach_source_invoices?: boolean;
             /** @description Language of the email. When omitted, the issuing company's `email_language` applies, and Spanish (`es`) when the company has none set. */
             language?: components["schemas"]["Language"];
         };
@@ -7873,7 +7873,7 @@ interface components {
                  */
                 total_including_tax?: number;
                 /** @default 0 */
-                discount_percentage: number;
+                discount_percentage?: number;
                 main_tax?: components["schemas"]["TaxInfo"];
                 /**
                  * @description Equivalence surcharge rate for this line of the corrective
@@ -9150,7 +9150,7 @@ interface components {
              *     without a year token must come with `counter_reset: NEVER`.
              * @default ANNUAL
              */
-            counter_reset: components["schemas"]["CounterReset"];
+            counter_reset?: components["schemas"]["CounterReset"];
             /**
              * Format: int64
              * @description Initial number for this series counter.
@@ -9163,12 +9163,12 @@ interface components {
              * @default 1
              * @example 1
              */
-            initial_number: number;
+            initial_number?: number;
             /**
              * @description Whether the series is active
              * @default true
              */
-            active: boolean;
+            active?: boolean;
             /**
              * @description Whether this is the default series for its document_type.
              *
@@ -9181,7 +9181,7 @@ interface components {
              *     the current default of that type.
              * @default false
              */
-            default_series: boolean;
+            default_series?: boolean;
         };
         /**
          * @description Request to **update** an invoice series (`PUT`). Despite the verb, this is a merge
@@ -10192,7 +10192,7 @@ interface components {
             payment_term_days?: number | null;
             notes?: string | null;
             /** @default false */
-            send_automatically: boolean;
+            send_automatically?: boolean;
             email_configuration?: components["schemas"]["RecurringEmailConfigRequest"];
         };
         CreateRecurringFromInvoiceRequest: {
@@ -10231,7 +10231,7 @@ interface components {
             /** Format: date */
             end_date?: string | null;
             /** @default false */
-            send_automatically: boolean;
+            send_automatically?: boolean;
             email_configuration?: components["schemas"]["RecurringEmailConfigRequest"];
         };
         /**
@@ -10443,7 +10443,7 @@ interface components {
              *     send `aeat_environment`.
              * @default TEST
              */
-            aeat_environment: components["schemas"]["Environment"];
+            aeat_environment?: components["schemas"]["Environment"];
             /**
              * @description Whether to **switch the company on** in `aeat_environment` as part of this call.
              *
@@ -10465,7 +10465,7 @@ interface components {
              *     `numbering` block or activate a mode in the same call.
              * @default true
              */
-            activate: boolean;
+            activate?: boolean;
         };
         /**
          * @description Editable fields of a company.
@@ -12289,7 +12289,7 @@ interface components {
              *     Without it such a void fails with `422 VOID_REQUIRES_ISSUED_IN_ERROR`.
              * @default false
              */
-            issued_in_error: boolean;
+            issued_in_error?: boolean;
             /**
              * Format: date
              * @deprecated
@@ -12309,7 +12309,7 @@ interface components {
              * @default false
              * @example false
              */
-            issue: boolean;
+            issue?: boolean;
         };
         /**
          * @description How to derive the new invoice from `from_invoice_id`.
@@ -12444,7 +12444,7 @@ interface components {
              * @default SUMMARY
              * @enum {string}
              */
-            format: "SUMMARY" | "ITEMS";
+            format?: "SUMMARY" | "ITEMS";
             /** @description Specific invoices to export. When present, `filters` is ignored. */
             invoice_ids?: components["schemas"]["UUID"][];
             filters?: components["schemas"]["InvoiceExportFilters"];
@@ -12989,7 +12989,7 @@ interface components {
             /** Format: date */
             end_date?: string | null;
             /** @default false */
-            send_automatically: boolean;
+            send_automatically?: boolean;
             email_configuration?: components["schemas"]["RecurringEmailConfigRequest"];
         };
         /**
@@ -13723,12 +13723,12 @@ interface components {
              * @description If `true`, an invitation email with the acceptance link is sent to `invited_email` in addition to returning the token. Defaults to `false` (you deliver the token/link yourself).
              * @default false
              */
-            send_email: boolean;
+            send_email?: boolean;
             /**
              * @description Initial grants (only when `account_role` is `MEMBER`). Omit it, or send `[]`, to invite with no company access yet (granted later). An explicit `null` is rejected with `422` `VALIDATION_ERROR`.
              * @default []
              */
-            grants: components["schemas"]["GrantAssignment"][];
+            grants?: components["schemas"]["GrantAssignment"][];
         };
         /** @description A created invitation. `token` is the single-use acceptance secret, returned only once (never exposed again); deliver it to the invitee. `invitation_url` is the ready-to-deliver acceptance link BeeL builds for the current environment from that same token. */
         Invitation: {
@@ -13842,7 +13842,7 @@ interface components {
              * @description Optional. When `true`, BeeL emails the account holder a claim link (`/reclamar?token=...`) so they can set their password and take ownership. Defaults to `false`: by default you receive the `claim_token` in the response and deliver it yourself. Requires a deliverable `email`: sending `true` without one returns `422`.
              * @default false
              */
-            send_email: boolean;
+            send_email?: boolean;
         };
         /** @description Result of a successful account provision. `claim_token` is a single-use secret to deliver to the account holder so they can set their password and take ownership. It is returned only once; `null` if the account was already claimed, `null` when the account was provisioned without `email` (there is no holder to hand it to yet), and `null` when a repeated provision found a claim link still valid (`claim_link_already_issued: true`). `claim_url` is the ready-to-use claim link BeeL builds for the current environment; `status` disambiguates a `null` `claim_token` (already claimed) from an error. */
         ProvisionAccountResult: {
@@ -13961,7 +13961,7 @@ interface components {
              *     What it did comes back in `own_company_customers`, apart from the per-account counters.
              * @default false
              */
-            apply_customers_to_own_company: boolean;
+            apply_customers_to_own_company?: boolean;
         };
         AccountImportUpload: {
             /**
@@ -15206,7 +15206,7 @@ interface components {
              * @description Which accounts this subscription receives events from. Defaults to `own`. Same field name and values as the `account_relationship` carried by every event envelope.
              * @default own
              */
-            account_relationship: components["schemas"]["WebhookAccountRelationship"];
+            account_relationship?: components["schemas"]["WebhookAccountRelationship"];
         };
         WebhookTestResult: {
             /** @description Whether your endpoint responded with HTTP 2xx. */
@@ -30917,18 +30917,44 @@ interface operations {
     };
 }
 
+/**
+ * Options of `new BeeL(config)`. Only `apiKey` is required.
+ *
+ * **Retries and idempotency.** A call is retried automatically, up to `maxRetries` times,
+ * only when sending it again can never apply it twice:
+ *
+ * - `429` is always retried, after `Retry-After`: the API refused the request unprocessed.
+ * - `409 IDEMPOTENCY_KEY_PROCESSING` is retried with the same key after `Retry-After`.
+ * - `5xx` and network errors are retried for `GET` requests and for requests that carry an
+ *   `Idempotency-Key` — every `POST` does, unless `autoIdempotencyKey` is `false`. A `5xx`
+ *   the API marks `Idempotency-Replay: true` is the stored outcome of that key and is not
+ *   retried: the same key would return it again.
+ * - `PUT`, `PATCH` and `DELETE` without a key are not retried after a `5xx` or network error.
+ *
+ * Every retry of a call reuses that call's `Idempotency-Key`, so an automatic retry never
+ * creates a second invoice. Two separate calls get two keys: to retry a create yourself
+ * after it failed with a `5xx` or a network error, use `invoices.createOnce`, or look the
+ * invoice up by `external_ref` before creating it again.
+ */
 interface BeeLConfig {
-    /** API key (beel_sk_live_* or beel_sk_test_*) */
+    /** API key: `beel_sk_live_*` (production) or `beel_sk_test_*` (sandbox). */
     apiKey: string;
-    /** Base URL. Defaults to https://app.beel.es/api */
+    /** Base URL. Default: `https://app.beel.es/api`. */
     baseUrl?: string;
-    /** Max retries on 429/5xx. Default: 3 */
+    /**
+     * Automatic retries after the first attempt, for the cases listed on {@link BeeLConfig}.
+     * `0` disables them. Default: `3`.
+     */
     maxRetries?: number;
-    /** Initial retry delay in ms. Default: 500 */
+    /** Base delay of the exponential backoff, in milliseconds. Default: `500`. */
     retryDelayMs?: number;
-    /** Max retry delay in ms. Default: 30000 */
+    /** Upper bound of any single wait between attempts, `Retry-After` included, in ms. Default: `30000`. */
     maxRetryDelayMs?: number;
-    /** Auto-generate Idempotency-Key for POST requests. Default: true */
+    /**
+     * Add one `Idempotency-Key` (a UUID) to every `POST` that does not carry its own, reused by
+     * every automatic retry of that call. With `false`, a `POST` without a key is only retried
+     * after a `429`. Default: `true`.
+     */
     autoIdempotencyKey?: boolean;
 }
 declare function createBeeLClient(config: BeeLConfig): openapi_fetch.Client<paths, `${string}/${string}`>;
@@ -30937,12 +30963,20 @@ type BeeLClient = ReturnType<typeof createBeeLClient>;
 type Invoice$1 = components['schemas']['Invoice'];
 type Pagination$5 = components['schemas']['Pagination'];
 type ListParams$2 = operations['listInvoices']['parameters']['query'];
+/**
+ * Invoices of the focused company, on the flat `/v1/invoices` routes.
+ *
+ * @deprecated The contract deprecates the session-focus routes. Use `beel.company(companyId).invoices` instead.
+ */
 declare class InvoicesResource {
     private client;
     constructor(client: BeeLClient);
     /**
      * 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 });
      */
@@ -30953,6 +30987,9 @@ declare class InvoicesResource {
     /**
      * 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',
@@ -31011,7 +31048,12 @@ declare class InvoicesResource {
         created_at: string;
         updated_at: string;
     }>;
-    /** Get an invoice by ID. */
+    /**
+     * Get an invoice by ID.
+     *
+     * @param id - Invoice UUID.
+     * @returns The invoice.
+     */
     get(id: string): Promise<{
         invoice_number?: string | null;
         series: components["schemas"]["SeriesInfo"];
@@ -31063,7 +31105,13 @@ declare class InvoicesResource {
         created_at: string;
         updated_at: string;
     }>;
-    /** 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.
+     */
     update(id: string, body: components['schemas']['UpdateInvoiceRequest']): Promise<{
         invoice_number?: string | null;
         series: components["schemas"]["SeriesInfo"];
@@ -31115,9 +31163,19 @@ declare class InvoicesResource {
         created_at: string;
         updated_at: string;
     }>;
-    /** Delete a draft invoice. Only draft invoices can be deleted. */
+    /**
+     * Delete a draft invoice. Only draft invoices can be deleted.
+     *
+     * @param id - Invoice UUID.
+     */
     delete(id: string): Promise<void>;
-    /** 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.
+     */
     duplicate(id: string, options?: {
         series_id?: string;
         notes?: string;
@@ -31174,7 +31232,10 @@ declare class InvoicesResource {
     }>;
     /**
      * 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.
      */
     issue(id: string, options?: {
         wait_for_pdf?: boolean;
@@ -31231,8 +31292,10 @@ declare class InvoicesResource {
     }>;
     /**
      * 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.
      */
     markPaid(id: string, options?: {
         payment_date?: string;
@@ -31288,7 +31351,13 @@ declare class InvoicesResource {
         created_at: string;
         updated_at: string;
     }>;
-    /** 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.
+     */
     markSent(id: string, options?: {
         sent_at?: string;
     }): Promise<{
@@ -31342,7 +31411,12 @@ declare class InvoicesResource {
         created_at: string;
         updated_at: string;
     }>;
-    /** 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`.
+     */
     revertToIssued(id: string): Promise<{
         invoice_number?: string | null;
         series: components["schemas"]["SeriesInfo"];
@@ -31397,6 +31471,10 @@ declare class InvoicesResource {
     /**
      * 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' });
      */
@@ -31454,7 +31532,13 @@ declare class InvoicesResource {
         created_at: string;
         updated_at: string;
     }>;
-    /** 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.
+     */
     createCorrective(id: string, body: components['schemas']['CreateCorrectiveInvoiceRequest']): Promise<{
         invoice_number?: string | null;
         series: components["schemas"]["SeriesInfo"];
@@ -31506,7 +31590,13 @@ declare class InvoicesResource {
         created_at: string;
         updated_at: string;
     }>;
-    /** 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.
+     */
     schedule(id: string, params: {
         scheduled_for: string;
         action?: string;
@@ -31561,7 +31651,12 @@ declare class InvoicesResource {
         created_at: string;
         updated_at: string;
     }>;
-    /** 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.
+     */
     unschedule(id: string): Promise<{
         invoice_number?: string | null;
         series: components["schemas"]["SeriesInfo"];
@@ -31613,7 +31708,13 @@ declare class InvoicesResource {
         created_at: string;
         updated_at: string;
     }>;
-    /** 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.
+     */
     reschedule(id: string, params: {
         scheduled_for: string;
     }): Promise<{
@@ -31670,13 +31771,22 @@ declare class InvoicesResource {
     /**
      * 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`.
      */
     getPdf(id: string): Promise<{
         download_url: string;
         expires_in_seconds: number;
         file_name: string;
     }>;
-    /** 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.
+     */
     sendEmail(id: string, options?: {
         to?: string[];
         cc?: string[];
@@ -31696,12 +31806,20 @@ declare class InvoicesResource {
 type Customer$1 = components['schemas']['Customer'];
 type Pagination$4 = components['schemas']['Pagination'];
 type ListParams$1 = operations['listCustomers']['parameters']['query'];
+/**
+ * Customers of the focused company, on the flat `/v1/customers` routes.
+ *
+ * @deprecated The contract deprecates the session-focus routes. Use `beel.company(companyId).customers` instead.
+ */
 declare class CustomersResource {
     private client;
     constructor(client: BeeLClient);
     /**
      * 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 });
      */
@@ -31712,6 +31830,9 @@ declare class CustomersResource {
     /**
      * 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',
@@ -31738,7 +31859,12 @@ declare class CustomersResource {
         updated_at?: string;
         alternative_id?: components["schemas"]["AlternativeIdentifier"];
     }>;
-    /** Get a customer by ID. */
+    /**
+     * Get a customer by ID.
+     *
+     * @param id - Customer UUID.
+     * @returns The customer.
+     */
     get(id: string): Promise<{
         id: string;
         legal_name: string;
@@ -31758,7 +31884,13 @@ declare class CustomersResource {
         updated_at?: string;
         alternative_id?: components["schemas"]["AlternativeIdentifier"];
     }>;
-    /** 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.
+     */
     update(id: string, body: components['schemas']['UpdateCustomerRequest']): Promise<{
         id: string;
         legal_name: string;
@@ -31778,19 +31910,31 @@ declare class CustomersResource {
         updated_at?: string;
         alternative_id?: components["schemas"]["AlternativeIdentifier"];
     }>;
-    /** Deactivate (soft-delete) a customer. */
+    /**
+     * Deactivate (soft-delete) a customer.
+     *
+     * @param id - Customer UUID.
+     */
     deactivate(id: string): Promise<void>;
 }
 
 type Product$1 = components['schemas']['Product'];
 type Pagination$3 = components['schemas']['Pagination'];
 type ListParams = operations['listProducts']['parameters']['query'];
+/**
+ * Products of the focused company, on the flat `/v1/products` routes.
+ *
+ * @deprecated The contract deprecates the session-focus routes. Use `beel.company(companyId).products` instead.
+ */
 declare class ProductsResource {
     private client;
     constructor(client: BeeLClient);
     /**
      * 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' });
      */
@@ -31801,6 +31945,9 @@ declare class ProductsResource {
     /**
      * 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',
@@ -31825,7 +31972,12 @@ declare class ProductsResource {
         created_at: string;
         updated_at: string;
     }>;
-    /** Get a product by ID. */
+    /**
+     * Get a product by ID.
+     *
+     * @param id - Product UUID.
+     * @returns The product.
+     */
     get(id: string): Promise<{
         id: string;
         code?: string | null;
@@ -31841,7 +31993,13 @@ declare class ProductsResource {
         created_at: string;
         updated_at: string;
     }>;
-    /** 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.
+     */
     update(id: string, body: components['schemas']['UpdateProductRequest']): Promise<{
         id: string;
         code?: string | null;
@@ -31857,11 +32015,19 @@ declare class ProductsResource {
         created_at: string;
         updated_at: string;
     }>;
-    /** Delete a product permanently. */
+    /**
+     * Delete a product permanently.
+     *
+     * @param id - Product UUID.
+     */
     delete(id: string): Promise<void>;
     /**
      * 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);
      */
@@ -31882,10 +32048,21 @@ declare class ProductsResource {
     }[]>;
 }
 
+/**
+ * Account-wide configuration on the flat `/v1/configuration/*` routes.
+ *
+ * @deprecated The contract deprecates these routes. Use
+ * `beel.company(companyId).taxConfiguration`, `beel.company(companyId).verifactuConfiguration`
+ * and {@link CatalogsResource} (`beel.catalogs`) instead.
+ */
 declare class ConfigurationResource {
     private client;
     constructor(client: BeeLClient);
-    /** Get the current tax configuration (default VAT, IRPF, etc.). */
+    /**
+     * Get the tax configuration (default VAT, IRPF…) of the focused company.
+     *
+     * @returns The tax configuration.
+     */
     getTaxConfig(): Promise<{
         default_main_tax: {
             type: components["schemas"]["TaxType"];
@@ -31907,7 +32084,12 @@ declare class ConfigurationResource {
             suggested_irpf_rate: number | null;
         } | undefined;
     } | undefined>;
-    /** Update tax configuration. */
+    /**
+     * Replace the tax configuration of the focused company.
+     *
+     * @param body - The complete tax configuration.
+     * @returns The stored configuration.
+     */
     updateTaxConfig(body: any): Promise<{
         default_main_tax: {
             type: components["schemas"]["TaxType"];
@@ -31929,7 +32111,11 @@ declare class ConfigurationResource {
             suggested_irpf_rate: number | null;
         } | undefined;
     } | undefined>;
-    /** 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.
+     */
     getTaxTypes(): Promise<{
         tax_regimes?: {
             code: "IVA" | "IGIC" | "IPSI" | "OTHER";
@@ -31972,7 +32158,11 @@ declare class ConfigurationResource {
             available_on_invoice_line: boolean;
         }[] | undefined;
     } | undefined>;
-    /** Get invoice customization options (logo, colors, footer text, etc.). */
+    /**
+     * Invoice customization options (templates, colors…).
+     *
+     * @returns The customization options.
+     */
     getInvoiceCustomizationOptions(): Promise<{
         template_types: {
             code: components["schemas"]["InvoiceTemplateType"];
@@ -31980,11 +32170,20 @@ declare class ConfigurationResource {
             description: string;
         }[];
     } | undefined>;
-    /** 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.
+     */
     updateLanguage(language: string): Promise<{
         language?: components["schemas"]["Language"] | undefined;
     } | undefined>;
-    /** Get VeriFactu configuration (enabled, certificate status, etc.). */
+    /**
+     * Get the VeriFactu configuration of the focused company.
+     *
+     * @returns The VeriFactu configuration.
+     */
     getVerifactu(): Promise<{
         enabled: boolean;
         nif_status?: "ACTIVATED" | "DEACTIVATED" | null | undefined;
@@ -31994,7 +32193,12 @@ declare class ConfigurationResource {
         activated?: boolean | null | undefined;
         pdf_generated?: boolean | null | undefined;
     } | undefined>;
-    /** Update VeriFactu configuration. */
+    /**
+     * Update the VeriFactu configuration of the focused company.
+     *
+     * @param body - `{ enabled }`.
+     * @returns The updated configuration.
+     */
     updateVerifactu(body: any): Promise<{
         enabled: boolean;
         nif_status?: "ACTIVATED" | "DEACTIVATED" | null | undefined;
@@ -32006,7 +32210,8 @@ declare class ConfigurationResource {
     } | undefined>;
 }
 /**
- * Account-wide catalogs and personal preferences, on their canonical paths.
+ * Account-wide catalogs, the credential's identity and personal preferences, on their
+ * canonical paths. Reach it as `beel.catalogs`.
  *
  * These replace the `/v1/configuration/*` reads on {@link ConfigurationResource},
  * whose flat routes are deprecated.
@@ -32014,7 +32219,32 @@ declare class ConfigurationResource {
 declare class CatalogsResource {
     private client;
     constructor(client: BeeLClient);
-    /** 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();
+     * ```
+     */
+    identity(): Promise<{
+        account_id: components["schemas"]["UUID"] & unknown;
+        name?: string | null;
+        email: components["schemas"]["Email"];
+        logo_url?: string | null;
+        language?: components["schemas"]["Language"] & unknown;
+        credential?: components["schemas"]["MyCredential"];
+    }>;
+    /**
+     * Tax types the API accepts. Canonical form of `configuration/tax-types`.
+     *
+     * @returns The tax types catalog.
+     */
     taxTypes(): Promise<{
         tax_regimes?: {
             code: "IVA" | "IGIC" | "IPSI" | "OTHER";
@@ -32057,7 +32287,11 @@ declare class CatalogsResource {
             available_on_invoice_line: boolean;
         }[] | undefined;
     } | undefined>;
-    /** 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.
+     */
     invoiceCustomizationOptions(): Promise<{
         template_types: {
             code: components["schemas"]["InvoiceTemplateType"];
@@ -32066,20 +32300,31 @@ declare class CatalogsResource {
         }[];
     } | undefined>;
     /**
-     * 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.
      */
     updateMe(body: components['schemas']['UpdateMeRequest']): Promise<{
         language: components["schemas"]["Language"];
     }>;
 }
 
+/**
+ * Invoice series of the focused company, on the flat `/v1/configuration/series` routes.
+ *
+ * @deprecated The contract deprecates the session-focus routes. Use `beel.company(companyId).series` instead.
+ */
 declare class SeriesResource {
     private client;
     constructor(client: BeeLClient);
     /**
      * 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);
@@ -32110,7 +32355,12 @@ declare class SeriesResource {
             has_previous?: boolean | undefined;
         } | undefined;
     } | undefined>;
-    /** 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.
+     */
     create(body: any): Promise<{
         id: string;
         document_type: components["schemas"]["DocumentType"];
@@ -32127,7 +32377,13 @@ declare class SeriesResource {
         readonly next_number?: number | undefined;
         updated_at?: string | undefined;
     } | undefined>;
-    /** 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.
+     */
     update(id: string, body: any): Promise<{
         id: string;
         document_type: components["schemas"]["DocumentType"];
@@ -32144,9 +32400,18 @@ declare class SeriesResource {
         readonly next_number?: number | undefined;
         updated_at?: string | undefined;
     } | undefined>;
-    /** Delete an invoice series. Only empty series can be deleted. */
+    /**
+     * Delete an invoice series. Only empty series can be deleted.
+     *
+     * @param id - Series UUID.
+     */
     delete(id: string): Promise<void>;
-    /** 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.
+     */
     setDefault(id: string): Promise<{
         id: string;
         document_type: components["schemas"]["DocumentType"];
@@ -32165,12 +32430,18 @@ declare class SeriesResource {
     } | undefined>;
 }
 
+/**
+ * NIF validation against the AEAT register. Reach it as `beel.nif`.
+ */
 declare class NifResource {
     private client;
     constructor(client: BeeLClient);
     /**
      * 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);
@@ -32191,7 +32462,10 @@ type WebhookSubscription = components['schemas']['WebhookSubscription'];
 type CompanyData = components['schemas']['CompanyData'];
 type Pagination$2 = components['schemas']['Pagination'];
 /**
- * Accounts managed by the API key holder (multi-account / OpenFleet-style provisioning).
+ * Accounts you provisioned and manage (multi-account provisioning for platforms and
+ * advisory firms). Reach it as `beel.accounts`; scope one with `beel.account(accountId)`.
+ *
+ * Every method rejects with a `BeeLApiError` subclass when the API answers non-2xx.
  *
  * @example
  * ```typescript
@@ -32203,14 +32477,24 @@ type Pagination$2 = components['schemas']['Pagination'];
 declare class AccountsResource {
     private client;
     constructor(client: BeeLClient);
-    /** 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`.
+     */
     list(params?: operations['listAccounts']['parameters']['query']): Promise<{
         accounts: ManagedAccountSummary[];
         next_cursor?: string | null;
     }>;
     /**
-     * Provision a new managed account. Answers with the provisioning result — the account
-     * id, its status and, when one is issued, the claim link — not with the account summary.
+     * 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.
      */
     provision(body: operations['provisionAccount']['requestBody']['content']['application/json']): Promise<{
         person_id?: string | null;
@@ -32221,7 +32505,12 @@ declare class AccountsResource {
         claim_link_already_issued: boolean;
         company_id?: string | null;
     }>;
-    /** Get a managed account by ID. */
+    /**
+     * Get a managed account.
+     *
+     * @param accountId - Account UUID.
+     * @returns The account summary.
+     */
     get(accountId: string): Promise<{
         account_id: string;
         external_ref: string;
@@ -32233,20 +32522,42 @@ declare class AccountsResource {
         representation_signed: boolean;
         created_at: string;
     }>;
-    /** 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: string): AccountScope;
 }
-/** Operations scoped to a single account. */
+/**
+ * Operations scoped to one account: its companies (NIFs), members, invitations, webhooks
+ * and usage. Reach it as `beel.account(accountId)`.
+ *
+ * @example
+ * ```typescript
+ * const { companies } = await beel.account('account-uuid').companies.list();
+ * const company = beel.company(companies[0].id!);
+ * ```
+ */
 declare class AccountScope {
     private client;
     readonly accountId: string;
+    /** Members of the account and their per-company grants. */
     readonly members: AccountMembersResource;
+    /** Invitations to join the account. */
     readonly invitations: AccountInvitationsResource;
+    /** Webhook subscriptions of the account. */
     readonly webhooks: AccountWebhooksResource;
+    /** Companies (NIFs) of the account — where company ids come from. */
     readonly companies: AccountCompaniesResource;
     constructor(client: BeeLClient, accountId: string);
     private path;
-    /** Get the account summary. */
+    /**
+     * Get the account summary.
+     *
+     * @returns The account summary.
+     */
     get(): Promise<{
         account_id: string;
         external_ref: string;
@@ -32258,30 +32569,59 @@ declare class AccountScope {
         representation_signed: boolean;
         created_at: string;
     }>;
-    /** Provisioning usage counters (accounts, NIFs) for billing purposes. */
+    /**
+     * Provisioning usage counters for billing: provisioned accounts and NIFs.
+     *
+     * @returns `provisioned_accounts` and `nifs`.
+     */
     usage(): Promise<{
         provisioned_accounts: number;
         nifs: number;
     }>;
-    /** 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`.
+     */
     changeAccessLevel(body: NonNullable<operations['changeManagedAccountAccessLevel']['requestBody']>['content']['application/json']): Promise<void>;
-    /** 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.
+     */
     endManagement(): Promise<void>;
-    /** 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`.
+     */
     createClaimToken(body?: NonNullable<operations['createAccountClaimToken']['requestBody']>['content']['application/json']): Promise<{
         person_id: string;
         claim_token: string;
         claim_url: string;
         expires_at: string;
     }>;
-    /** 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.
+     */
     setOwner(body: operations['putAccountOwner']['requestBody']['content']['application/json']): Promise<void>;
 }
-/** Members of an account and their per-company grants. */
+/**
+ * Members of an account and their per-company grants. Reach it as
+ * `beel.account(accountId).members`.
+ */
 declare class AccountMembersResource {
     private client;
     private accountId;
     constructor(client: BeeLClient, accountId: string);
+    /**
+     * List the account's members.
+     *
+     * @returns The members (`data.members` of the response), as an array.
+     */
     list(): Promise<{
         member_id: string;
         person_id: string;
@@ -32290,6 +32630,12 @@ declare class AccountMembersResource {
         grants?: components["schemas"]["MemberGrant"][];
         permissions: components["schemas"]["MemberPermissions"];
     }[]>;
+    /**
+     * Get one member.
+     *
+     * @param memberId - Member UUID.
+     * @returns The member.
+     */
     get(memberId: string): Promise<{
         member_id: string;
         person_id: string;
@@ -32298,7 +32644,13 @@ declare class AccountMembersResource {
         grants?: components["schemas"]["MemberGrant"][];
         permissions: components["schemas"]["MemberPermissions"];
     }>;
-    /** 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.
+     */
     update(memberId: string, body: operations['patchAccountMember']['requestBody']['content']['application/json']): Promise<{
         member_id: string;
         person_id: string;
@@ -32307,9 +32659,18 @@ declare class AccountMembersResource {
         grants?: components["schemas"]["MemberGrant"][];
         permissions: components["schemas"]["MemberPermissions"];
     }>;
-    /** Remove a member from the account. */
+    /**
+     * Remove a member from the account.
+     *
+     * @param memberId - Member UUID.
+     */
     remove(memberId: string): Promise<void>;
-    /** List a member's per-company grants. */
+    /**
+     * List a member's per-company grants.
+     *
+     * @param memberId - Member UUID.
+     * @returns The `grants` and their `pagination`.
+     */
     listGrants(memberId: string): Promise<{
         grants: {
             company_id: string;
@@ -32325,19 +32686,36 @@ declare class AccountMembersResource {
             has_previous?: boolean | undefined;
         };
     } | undefined>;
-    /** 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.
+     */
     putGrant(memberId: string, companyId: string, body: operations['putAccountMemberGrant']['requestBody']['content']['application/json']): Promise<{
         company_id: string;
         access_level: "VIEW" | "OPERATE";
     } | undefined>;
-    /** Revoke a member's grant over one company. */
+    /**
+     * Revoke a member's access to one company.
+     *
+     * @param memberId - Member UUID.
+     * @param companyId - Company UUID.
+     */
     removeGrant(memberId: string, companyId: string): Promise<void>;
 }
-/** Invitations to join an account. */
+/** Invitations to join an account. Reach it as `beel.account(accountId).invitations`. */
 declare class AccountInvitationsResource {
     private client;
     private accountId;
     constructor(client: BeeLClient, accountId: string);
+    /**
+     * List the account's invitations.
+     *
+     * @returns The invitations.
+     */
     list(): Promise<{
         invitations: {
             invitation_id: string;
@@ -32356,6 +32734,12 @@ declare class AccountInvitationsResource {
             has_previous?: boolean | undefined;
         };
     }>;
+    /**
+     * Invite someone to join the account.
+     *
+     * @param body - `invited_email` and the `account_role` to grant.
+     * @returns The invitation.
+     */
     create(body: operations['createAccountInvitation']['requestBody']['content']['application/json']): Promise<{
         invitation_id: string;
         invited_email: string;
@@ -32364,6 +32748,12 @@ declare class AccountInvitationsResource {
         token: string;
         invitation_url?: string | null;
     }>;
+    /**
+     * Get one invitation.
+     *
+     * @param invitationId - Invitation UUID.
+     * @returns The invitation.
+     */
     get(invitationId: string): Promise<{
         invitation_id: string;
         invited_email: string;
@@ -32372,17 +32762,37 @@ declare class AccountInvitationsResource {
         created_at: string;
         expires_at: string;
     }>;
+    /**
+     * Revoke a `PENDING` invitation, so its link stops working.
+     *
+     * @param invitationId - Invitation UUID.
+     */
     revoke(invitationId: string): Promise<void>;
 }
-/** Webhook subscriptions scoped to a managed account. */
+/**
+ * Webhook subscriptions of an account. Reach it as `beel.account(accountId).webhooks`;
+ * verify deliveries with `WebhookVerifier`.
+ */
 declare class AccountWebhooksResource {
     private client;
     private accountId;
     constructor(client: BeeLClient, accountId: string);
+    /**
+     * List the webhook subscriptions.
+     *
+     * @param params - Pagination.
+     * @returns The `webhooks` and their `pagination`.
+     */
     list(params?: operations['listAccountWebhookSubscriptions']['parameters']['query']): Promise<{
         webhooks?: WebhookSubscription[];
         pagination?: Pagination$2;
     }>;
+    /**
+     * Subscribe an HTTPS endpoint to events.
+     *
+     * @param body - `url` and the `events` to receive.
+     * @returns The subscription, with its signing secret.
+     */
     create(body: operations['createAccountWebhookSubscription']['requestBody']['content']['application/json']): Promise<{
         id: string;
         url: string;
@@ -32405,6 +32815,12 @@ declare class AccountWebhooksResource {
             failure_cause?: components["schemas"]["WebhookFailureCause"] | undefined;
         } | null | undefined;
     } | undefined>;
+    /**
+     * Get one webhook subscription.
+     *
+     * @param webhookId - Subscription UUID.
+     * @returns The subscription.
+     */
     get(webhookId: string): Promise<{
         id: string;
         url: string;
@@ -32419,6 +32835,13 @@ declare class AccountWebhooksResource {
         last_used_at?: string | null;
         created_at: string;
     }>;
+    /**
+     * Update a webhook subscription. Only the fields present in `body` change.
+     *
+     * @param webhookId - Subscription UUID.
+     * @param body - Fields to change.
+     * @returns The updated subscription.
+     */
     update(webhookId: string, body: operations['patchAccountWebhookSubscription']['requestBody']['content']['application/json']): Promise<{
         id: string;
         url: string;
@@ -32433,8 +32856,18 @@ declare class AccountWebhooksResource {
         last_used_at?: string | null;
         created_at: string;
     }>;
+    /**
+     * Delete a webhook subscription.
+     *
+     * @param webhookId - Subscription UUID.
+     */
     delete(webhookId: string): Promise<void>;
-    /** 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.
+     */
     test(webhookId: string): Promise<{
         delivery_success?: boolean | undefined;
         http_status?: number | null | undefined;
@@ -32442,7 +32875,12 @@ declare class AccountWebhooksResource {
         error?: string | null | undefined;
         failure_cause?: components["schemas"]["WebhookFailureCause"] | undefined;
     } | undefined>;
-    /** 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.
+     */
     rotateSecret(webhookId: string): Promise<{
         id: string;
         url: string;
@@ -32465,6 +32903,13 @@ declare class AccountWebhooksResource {
             failure_cause?: components["schemas"]["WebhookFailureCause"] | undefined;
         } | null | undefined;
     } | undefined>;
+    /**
+     * List the delivery attempts of a subscription.
+     *
+     * @param webhookId - Subscription UUID.
+     * @param params - Filters and pagination.
+     * @returns The deliveries.
+     */
     listDeliveries(webhookId: string, params?: operations['listAccountWebhookDeliveries']['parameters']['query']): Promise<{
         deliveries?: {
             id?: string | undefined;
@@ -32494,6 +32939,13 @@ declare class AccountWebhooksResource {
             has_previous?: boolean | undefined;
         } | undefined;
     } | undefined>;
+    /**
+     * Retry a failed delivery.
+     *
+     * @param webhookId - Subscription UUID.
+     * @param deliveryId - Delivery UUID.
+     * @returns The new delivery attempt.
+     */
     retryDelivery(webhookId: string, deliveryId: string): Promise<{
         id?: string | undefined;
         subscription_id?: string | undefined;
@@ -32514,16 +32966,37 @@ declare class AccountWebhooksResource {
         delivered_at?: string | undefined;
     } | undefined>;
 }
-/** Companies (NIFs) that live under a managed account. */
+/**
+ * Companies (NIFs) of an account — where the `companyId` of `beel.company(companyId)`
+ * comes from. Reach it as `beel.account(accountId).companies`.
+ */
 declare class AccountCompaniesResource {
     private client;
     private accountId;
     constructor(client: BeeLClient, accountId: string);
-    list(params?: operations['listCompanies']['parameters']['query']): Promise<{
+    /**
+     * 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!);
+     * ```
+     */
+    list(params?: operations['listCompanies']['parameters']['query']): Promise<{
         companies: CompanyData[];
         pagination: Pagination$2 | undefined;
     }>;
-    /** 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.
+     */
     create(body: components['schemas']['CreateCompanyRequest']): Promise<{
         id?: string;
         access_level?: components["schemas"]["AccessLevel"];
@@ -32570,7 +33043,11 @@ declare class AccountCompaniesResource {
         created_at?: string;
         readiness?: components["schemas"]["IssuingReadinessData"] | null;
     }>;
-    /** 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.
+     */
     stats(): Promise<{
         stats: {
             company_id: string;
@@ -32588,6 +33065,31 @@ declare class AccountCompaniesResource {
     } | undefined>;
 }
 
+/**
+ * Per-call options, accepted as the last argument of the `company.invoices` methods.
+ *
+ * @example
+ * ```typescript
+ * await company.invoices.create(body, undefined, {
+ *   idempotencyKey: `order-${order.id}`,
+ *   timeoutMs: 15_000,
+ * });
+ * ```
+ */
+interface RequestOptions {
+    /**
+     * `Idempotency-Key` of this call, instead of the automatic one: letters, digits, `_` and
+     * `-`, up to 255 characters. Every automatic retry of the call reuses it. Persist it with
+     * your order to retry the same operation later: within 24 hours the API replays the first
+     * `2xx` or `5xx` answer instead of running the operation again.
+     */
+    idempotencyKey?: string;
+    /** Aborts the call — the automatic retries and the waits between them included. */
+    signal?: AbortSignal;
+    /** Aborts the call after this many milliseconds, automatic retries included. */
+    timeoutMs?: number;
+}
+
 type ManagedPaymentConnection = components['schemas']['ManagedPaymentConnection'];
 type ManagedPaymentEvent = components['schemas']['ManagedPaymentEvent'];
 type Pagination$1 = components['schemas']['Pagination'];
@@ -32614,7 +33116,11 @@ declare class CompanyPaymentConnectionsResource {
     private companyId;
     constructor(client: BeeLClient, companyId: string);
     private path;
-    /** Every payment connection of this company. */
+    /**
+     * Every payment connection of this company.
+     *
+     * @returns The `connections`.
+     */
     list(): Promise<{
         connections: ManagedPaymentConnection[];
     }>;
@@ -32622,11 +33128,20 @@ declare class CompanyPaymentConnectionsResource {
      * 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.
      */
     authorize(body: components['schemas']['InitiatePaymentConnectionRequest']): Promise<{
         authorization_url: string;
     }>;
-    /** 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.
+     */
     update(connectionId: string, body: components['schemas']['UpdateCompanyPaymentConnectionRequest']): Promise<{
         id: string;
         provider: string;
@@ -32650,14 +33165,22 @@ declare class CompanyPaymentConnectionsResource {
     /**
      * Disconnect one connection. Tokens are revoked and auto-invoicing stops;
      * already-issued invoices are untouched.
+     *
+     * @param connectionId - Connection UUID.
      */
     disconnect(connectionId: string): Promise<void>;
-    /** 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: string): CompanyPaymentEventsResource;
 }
 /**
  * Payment events received through a connection, and the recovery levers for the ones
- * that did not produce an invoice.
+ * that did not produce an invoice. Reach it as
+ * `beel.company(companyId).paymentConnections.events(connectionId)`.
  */
 declare class CompanyPaymentEventsResource {
     private client;
@@ -32669,13 +33192,21 @@ declare class CompanyPaymentEventsResource {
      * 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`.
      */
     list(params?: operations['listCompanyPaymentEvents']['parameters']['query']): Promise<{
         events: ManagedPaymentEvent[];
         pagination?: Pagination$1;
         counts?: PaymentEventCounts;
     }>;
-    /** One event. */
+    /**
+     * Get one event.
+     *
+     * @param eventId - Event UUID.
+     * @returns The event.
+     */
     get(eventId: string): Promise<{
         id: string;
         provider: string;
@@ -32714,6 +33245,9 @@ declare class CompanyPaymentEventsResource {
      * 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.
      */
     retry(eventId: string): Promise<{
         id: string;
@@ -32751,12 +33285,20 @@ declare class CompanyPaymentEventsResource {
     }>;
     /**
      * 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`.
      */
     draft(eventId: string): Promise<{
         invoice_id: string;
     }>;
-    /** 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.
+     */
     resolve(eventId: string): Promise<{
         id: string;
         provider: string;
@@ -32791,7 +33333,12 @@ declare class CompanyPaymentEventsResource {
         discarded: boolean;
         discarded_at?: string | null;
     }>;
-    /** 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.
+     */
     discard(eventId: string): Promise<{
         id: string;
         provider: string;
@@ -32826,7 +33373,12 @@ declare class CompanyPaymentEventsResource {
         discarded: boolean;
         discarded_at?: string | null;
     }>;
-    /** Bring a discarded event back into the list. */
+    /**
+     * Bring a discarded event back into the list.
+     *
+     * @param eventId - Event UUID.
+     * @returns The restored event.
+     */
     restore(eventId: string): Promise<{
         id: string;
         provider: string;
@@ -32863,6 +33415,26 @@ declare class CompanyPaymentEventsResource {
     }>;
 }
 
+type CreateInvoiceRequest$1 = components['schemas']['CreateInvoiceRequest'];
+/**
+ * Invoice types whose `external_ref` the API keeps unique: at most one live (not deleted)
+ * invoice of these types per reference and environment, whatever its status — a `VOIDED`
+ * one included. Correctives are exempt, and proformas are not covered.
+ */
+declare const EXTERNAL_REF_UNIQUE_INVOICE_TYPES: readonly ["STANDARD", "SIMPLIFIED"];
+/** Invoice types {@link createInvoiceOnce} accepts. */
+type ExternalRefUniqueInvoiceType = (typeof EXTERNAL_REF_UNIQUE_INVOICE_TYPES)[number];
+/**
+ * Body of `invoices.createOnce`: a `CreateInvoiceRequest` whose `type` is `STANDARD` or
+ * `SIMPLIFIED` and whose `external_ref` is required — it is what makes the call safe to repeat.
+ */
+type CreateInvoiceOnceRequest = Omit<CreateInvoiceRequest$1, 'type' | 'external_ref'> & {
+    type: ExternalRefUniqueInvoiceType;
+    external_ref: string;
+};
+/** Query of `invoices.createOnce`: the same as `invoices.create`. */
+type CreateInvoiceOnceParams = operations['createCompanyInvoice']['parameters']['query'];
+
 type Invoice = components['schemas']['Invoice'];
 type Customer = components['schemas']['Customer'];
 type Product = components['schemas']['Product'];
@@ -32870,7 +33442,10 @@ type Pagination = components['schemas']['Pagination'];
 /**
  * Operations scoped to a single company (NIF). This is the explicit multi-NIF surface:
  * the company is addressed in the path, so no session focus or `BeeL-Active-Company`
- * header is needed.
+ * header is needed. Get one with `beel.company(companyId)`; list the ids with
+ * `beel.account(accountId).companies.list()`.
+ *
+ * Every method rejects with a `BeeLApiError` subclass when the API answers non-2xx.
  *
  * @example
  * ```typescript
@@ -32882,17 +33457,30 @@ type Pagination = components['schemas']['Pagination'];
 declare class CompanyScope {
     private client;
     readonly companyId: string;
+    /** Invoices of this company: create, issue, void, correct, list, PDF, email. */
     readonly invoices: CompanyInvoicesResource;
+    /** Customers of this company. */
     readonly customers: CompanyCustomersResource;
+    /** Products and services of this company. */
     readonly products: CompanyProductsResource;
+    /** Invoice series (numbering) of this company. */
     readonly series: CompanySeriesResource;
+    /** Recurring invoice templates of this company. */
     readonly recurringInvoices: CompanyRecurringInvoicesResource;
+    /** Payment provider connections (Stripe) that auto-generate invoices under this NIF. */
     readonly paymentConnections: CompanyPaymentConnectionsResource;
+    /** Default taxes of this company. */
     readonly taxConfiguration: CompanyTaxConfigurationResource;
+    /** Whether this NIF submits its invoices to AEAT under VeriFactu. */
     readonly verifactuConfiguration: CompanyVeriFactuConfigurationResource;
     constructor(client: BeeLClient, companyId: string);
     private path;
-    /** Get the company. */
+    /**
+     * Get the company: its fiscal identity, address and settings.
+     *
+     * @param params - Optional query of `getCompanyById` (e.g. `include`).
+     * @returns The company.
+     */
     get(params?: operations['getCompanyById']['parameters']['query']): Promise<{
         id?: string;
         access_level?: components["schemas"]["AccessLevel"];
@@ -32939,7 +33527,12 @@ declare class CompanyScope {
         created_at?: string;
         readiness?: components["schemas"]["IssuingReadinessData"] | null;
     }>;
-    /** Update company data. */
+    /**
+     * Update the company's data. Only the fields present in `body` change.
+     *
+     * @param body - Fields to change.
+     * @returns The updated company.
+     */
     update(body: components['schemas']['UpdateCompanyRequest']): Promise<{
         id?: string;
         access_level?: components["schemas"]["AccessLevel"];
@@ -32986,9 +33579,17 @@ declare class CompanyScope {
         created_at?: string;
         readiness?: components["schemas"]["IssuingReadinessData"] | null;
     }>;
-    /** Delete the company. */
+    /**
+     * Remove the company from its account. Blocked for the primary NIF, a NIF active in Live,
+     * or one holding Live invoices.
+     */
     delete(): Promise<void>;
-    /** 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.
+     */
     fiscalSummary(params?: operations['getCompanyFiscalSummary']['parameters']['query']): Promise<{
         queried_period: components["schemas"]["QueriedPeriod"];
         total_taxable_base: number;
@@ -33008,7 +33609,11 @@ declare class CompanyScope {
         invoices?: components["schemas"]["InvoiceFiscalData"][];
         total_invoices: number;
     }>;
-    /** 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`.
+     */
     issuingReadiness(): Promise<{
         ready?: boolean;
         blockers?: ("COMPANY_HAS_NO_NIF" | "SERIES_DEFAULT_NOT_FOUND" | "PROFILE_INCOMPLETE" | "COMPANY_NOT_ACTIVATED" | "ENV_MISMATCH" | "NIF_NOT_REGISTERED" | "NIF_REPRESENTATION_REQUIRED")[];
@@ -33018,16 +33623,28 @@ declare class CompanyScope {
         };
     }>;
 }
-/** Invoice lifecycle addressed per company. */
+/**
+ * Invoice lifecycle of one company: create a draft (or issue it directly), issue, void,
+ * correct, list and read, PDF and email. Reach it as `beel.company(companyId).invoices`.
+ *
+ * A create, issue, void or corrective carries an automatic `Idempotency-Key`, reused by the
+ * client's automatic retries. To retry a create yourself safely, use {@link createOnce}.
+ */
 declare class CompanyInvoicesResource {
     private client;
     private companyId;
+    /** Scheduled issuing of one invoice: read, set or clear it. */
     readonly schedule: CompanyInvoiceScheduleResource;
     constructor(client: BeeLClient, companyId: string);
     /**
-     * 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.
      */
-    derive(body: components['schemas']['CreateInvoiceDerivationRequest']): Promise<{
+    derive(body: components['schemas']['CreateInvoiceDerivationRequest'], options?: RequestOptions): Promise<{
         invoice_number?: string | null;
         series: components["schemas"]["SeriesInfo"];
         number?: number | null;
@@ -33079,11 +33696,51 @@ declare class CompanyInvoicesResource {
         updated_at: string;
     }>;
     private path;
-    list(params?: operations['listCompanyInvoices']['parameters']['query']): Promise<{
+    /**
+     * 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' });
+     * ```
+     */
+    list(params?: operations['listCompanyInvoices']['parameters']['query'], options?: RequestOptions): Promise<{
         invoices: Invoice[];
         pagination: Pagination;
     }>;
-    create(body: components['schemas']['CreateInvoiceRequest'], params?: operations['createCompanyInvoice']['parameters']['query']): Promise<{
+    /**
+     * 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',
+     * });
+     * ```
+     */
+    create(body: components['schemas']['CreateInvoiceRequest'], params?: operations['createCompanyInvoice']['parameters']['query'], options?: RequestOptions): Promise<{
         invoice_number?: string | null;
         series: components["schemas"]["SeriesInfo"];
         number?: number | null;
@@ -33134,7 +33791,99 @@ declare class CompanyInvoicesResource {
         created_at: string;
         updated_at: string;
     }>;
-    get(invoiceId: string): Promise<{
+    /**
+     * 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 },
+     * });
+     * ```
+     */
+    createOnce(body: CreateInvoiceOnceRequest, params?: CreateInvoiceOnceParams, options?: RequestOptions): Promise<{
+        invoice_number?: string | null;
+        series: components["schemas"]["SeriesInfo"];
+        number?: number | null;
+        type: components["schemas"]["InvoiceType"];
+        status: components["schemas"]["InvoiceStatus"];
+        issue_date: string;
+        operation_date?: string | null;
+        due_date?: string;
+        valid_until?: string | null;
+        payment_date?: string;
+        sent_at?: string | null;
+        paid_at?: string | null;
+        auto_emit_after?: string | null;
+        scheduled_for?: string | null;
+        scheduled_action?: components["schemas"]["GenerationAction"];
+        issuer: components["schemas"]["IssuerData"];
+        recipient: components["schemas"]["RecipientData"];
+        lines: components["schemas"]["InvoiceLine"][];
+        totals: components["schemas"]["InvoiceTotals"];
+        payment_info?: components["schemas"]["PaymentInfo"];
+        notes?: string;
+        replaced_invoice_ids?: string[];
+        void_cause?: components["schemas"]["VoidCause"];
+        void_reason?: string;
+        voided_at?: string | null;
+        rectified_invoice_id?: string;
+        source_proforma_id?: string;
+        converted_invoice_id?: string;
+        rectification_reason?: string;
+        recurring_invoice_id?: string | null;
+        recurring_invoice_name?: string | null;
+        rectification_type?: components["schemas"]["RectificationType"];
+        rectification_code?: components["schemas"]["VeriFactuRectificationCode"];
+        external_ref?: string | null;
+        metadata?: {
+            [key: string]: unknown;
+        };
+        send_automatically?: boolean | null;
+        email_config?: components["schemas"]["EmailConfiguration"] | null;
+        pdf_download_url?: string | null;
+        verifactu?: components["schemas"]["VeriFactu"];
+        attachments?: components["schemas"]["InvoiceAttachment"][];
+        sending_history?: components["schemas"]["InvoiceSendRecord"][];
+        email_delivery?: components["schemas"]["InvoiceEmailDeliveryOutcome"];
+        deleted_at?: string | null;
+    } & {
+        id: string;
+        created_at: string;
+        updated_at: string;
+    }>;
+    /**
+     * 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.
+     */
+    get(invoiceId: string, options?: RequestOptions): Promise<{
         invoice_number?: string | null;
         series: components["schemas"]["SeriesInfo"];
         number?: number | null;
@@ -33185,8 +33934,16 @@ declare class CompanyInvoicesResource {
         created_at: string;
         updated_at: string;
     }>;
-    /** Update a draft invoice. */
-    update(invoiceId: string, body: operations['patchCompanyInvoice']['requestBody']['content']['application/json']): Promise<{
+    /**
+     * 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.
+     */
+    update(invoiceId: string, body: operations['patchCompanyInvoice']['requestBody']['content']['application/json'], options?: RequestOptions): Promise<{
         invoice_number?: string | null;
         series: components["schemas"]["SeriesInfo"];
         number?: number | null;
@@ -33237,10 +33994,23 @@ declare class CompanyInvoicesResource {
         created_at: string;
         updated_at: string;
     }>;
-    /** Delete a draft invoice. */
-    delete(invoiceId: string): Promise<void>;
-    /** Issue a draft invoice (assigns number, submits to VeriFactu when configured). */
-    issue(invoiceId: string, params?: operations['issueCompanyInvoice']['parameters']['query']): Promise<{
+    /**
+     * 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`.
+     */
+    delete(invoiceId: string, options?: RequestOptions): Promise<void>;
+    /**
+     * 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.
+     */
+    issue(invoiceId: string, params?: operations['issueCompanyInvoice']['parameters']['query'], options?: RequestOptions): Promise<{
         invoice_number?: string | null;
         series: components["schemas"]["SeriesInfo"];
         number?: number | null;
@@ -33291,8 +34061,16 @@ declare class CompanyInvoicesResource {
         created_at: string;
         updated_at: string;
     }>;
-    /** Void an issued invoice. */
-    void(invoiceId: string, body: NonNullable<operations['voidCompanyInvoice']['requestBody']>['content']['application/json']): Promise<{
+    /**
+     * 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.
+     */
+    void(invoiceId: string, body: NonNullable<operations['voidCompanyInvoice']['requestBody']>['content']['application/json'], options?: RequestOptions): Promise<{
         invoice_number?: string | null;
         series: components["schemas"]["SeriesInfo"];
         number?: number | null;
@@ -33343,8 +34121,27 @@ declare class CompanyInvoicesResource {
         created_at: string;
         updated_at: string;
     }>;
-    /** Create a corrective (rectificativa) for an issued invoice. */
-    createCorrective(invoiceId: string, body: operations['createCompanyCorrectiveInvoice']['requestBody']['content']['application/json']): Promise<{
+    /**
+     * 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' } }],
+     * });
+     * ```
+     */
+    createCorrective(invoiceId: string, body: operations['createCompanyCorrectiveInvoice']['requestBody']['content']['application/json'], options?: RequestOptions): Promise<{
         invoice_number?: string | null;
         series: components["schemas"]["SeriesInfo"];
         number?: number | null;
@@ -33395,8 +34192,15 @@ declare class CompanyInvoicesResource {
         created_at: string;
         updated_at: string;
     }>;
-    /** Convert a proforma into an invoice. */
-    convertToInvoice(invoiceId: string, body?: NonNullable<operations['convertCompanyProformaToInvoice']['requestBody']>['content']['application/json']): Promise<{
+    /**
+     * 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.
+     */
+    convertToInvoice(invoiceId: string, body?: NonNullable<operations['convertCompanyProformaToInvoice']['requestBody']>['content']['application/json'], options?: RequestOptions): Promise<{
         invoice_number?: string | null;
         series: components["schemas"]["SeriesInfo"];
         number?: number | null;
@@ -33453,6 +34257,10 @@ declare class CompanyInvoicesResource {
      * 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({
@@ -33461,7 +34269,7 @@ declare class CompanyInvoicesResource {
      * });
      * ```
      */
-    createSimplifiedExchange(body: components['schemas']['CreateSimplifiedExchangeRequest']): Promise<{
+    createSimplifiedExchange(body: components['schemas']['CreateSimplifiedExchangeRequest'], options?: RequestOptions): Promise<{
         invoice_number?: string | null;
         series: components["schemas"]["SeriesInfo"];
         number?: number | null;
@@ -33515,8 +34323,12 @@ declare class CompanyInvoicesResource {
     /**
      * 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`.
      */
-    verifactuRecords(invoiceId: string): Promise<{
+    verifactuRecords(invoiceId: string, options?: RequestOptions): Promise<{
         id: string;
         operation: components["schemas"]["VeriFactuRecordOperation"];
         submission_status?: components["schemas"]["VeriFactuSubmissionStatus"];
@@ -33527,8 +34339,16 @@ declare class CompanyInvoicesResource {
         error_code?: string | null;
         error_message?: string | null;
     }[]>;
-    /** Update payment status (e.g. mark as paid). */
-    setStatus(invoiceId: string, body: operations['setCompanyInvoiceStatus']['requestBody']['content']['application/json']): Promise<{
+    /**
+     * 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.
+     */
+    setStatus(invoiceId: string, body: operations['setCompanyInvoiceStatus']['requestBody']['content']['application/json'], options?: RequestOptions): Promise<{
         invoice_number?: string | null;
         series: components["schemas"]["SeriesInfo"];
         number?: number | null;
@@ -33579,14 +34399,27 @@ declare class CompanyInvoicesResource {
         created_at: string;
         updated_at: string;
     }>;
-    /** Get PDF metadata and download URL. */
-    getPdf(invoiceId: string): Promise<{
+    /**
+     * 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`.
+     */
+    getPdf(invoiceId: string, options?: RequestOptions): Promise<{
         download_url: string;
         expires_in_seconds: number;
         file_name: string;
     }>;
-    /** Send the invoice by email to the customer. */
-    send(invoiceId: string, body: NonNullable<operations['sendCompanyInvoice']['requestBody']>['content']['application/json']): Promise<{
+    /**
+     * 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.
+     */
+    send(invoiceId: string, body: NonNullable<operations['sendCompanyInvoice']['requestBody']>['content']['application/json'], options?: RequestOptions): Promise<{
         email_id?: components["schemas"]["UUID"] | undefined;
         sent_to?: string[] | undefined;
         sent_at?: string | undefined;
@@ -33596,12 +34429,20 @@ declare class CompanyInvoicesResource {
         sent_at?: string | undefined;
     } | undefined>;
 }
-/** Customers addressed per company. */
-/** Schedule of one invoice: read it, set it, clear it. */
+/**
+ * Scheduled issuing of one invoice: read it, set it, clear it. Reach it as
+ * `beel.company(companyId).invoices.schedule`.
+ */
 declare class CompanyInvoiceScheduleResource {
     private client;
     private companyId;
     constructor(client: BeeLClient, companyId: string);
+    /**
+     * Get the schedule of an invoice.
+     *
+     * @param invoiceId - Invoice UUID.
+     * @returns `scheduled_for` and `generation_mode`.
+     */
     get(invoiceId: string): Promise<{
         scheduled_for: string;
         generation_mode: components["schemas"]["GenerationAction"];
@@ -33609,6 +34450,10 @@ declare class CompanyInvoiceScheduleResource {
     /**
      * 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.
      */
     set(invoiceId: string, body: components['schemas']['SetInvoiceScheduleRequest']): Promise<{
         invoice_number?: string | null | undefined;
@@ -33792,17 +34637,35 @@ declare class CompanyInvoiceScheduleResource {
         created_at: string;
         updated_at: string;
     } | undefined>;
-    /** 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.
+     */
     clear(invoiceId: string): Promise<void>;
 }
+/** Customers of one company. Reach it as `beel.company(companyId).customers`. */
 declare class CompanyCustomersResource {
     private client;
     private companyId;
     constructor(client: BeeLClient, companyId: string);
+    /**
+     * List the company's customers, paginated and searchable.
+     *
+     * @param params - Filters and pagination.
+     * @returns The page of `customers` and its `pagination`.
+     */
     list(params?: operations['listCompanyCustomers']['parameters']['query']): Promise<{
         customers: Customer[];
         pagination: Pagination;
     }>;
+    /**
+     * Create a customer.
+     *
+     * @param body - Legal name, NIF (or alternative id) and address.
+     * @returns The created customer.
+     */
     create(body: components['schemas']['CreateCustomerRequest']): Promise<{
         id: string;
         legal_name: string;
@@ -33822,6 +34685,12 @@ declare class CompanyCustomersResource {
         updated_at?: string;
         alternative_id?: components["schemas"]["AlternativeIdentifier"];
     }>;
+    /**
+     * Create several customers in one call.
+     *
+     * @param body - The customers, and whether it is a dry run.
+     * @returns Per-customer results and totals.
+     */
     createBulk(body: operations['createCompanyCustomersBulk']['requestBody']['content']['application/json']): Promise<{
         metadata: {
             total_customers: number;
@@ -33896,6 +34765,12 @@ declare class CompanyCustomersResource {
             not_importable?: number | undefined;
         };
     } | undefined>;
+    /**
+     * Get one customer.
+     *
+     * @param customerId - Customer UUID.
+     * @returns The customer.
+     */
     get(customerId: string): Promise<{
         id: string;
         legal_name: string;
@@ -33915,6 +34790,13 @@ declare class CompanyCustomersResource {
         updated_at?: string;
         alternative_id?: components["schemas"]["AlternativeIdentifier"];
     }>;
+    /**
+     * Update a customer. Only the fields present in `body` change.
+     *
+     * @param customerId - Customer UUID.
+     * @param body - Fields to change.
+     * @returns The updated customer.
+     */
     update(customerId: string, body: operations['patchCompanyCustomer']['requestBody']['content']['application/json']): Promise<{
         id: string;
         legal_name: string;
@@ -33934,17 +34816,35 @@ declare class CompanyCustomersResource {
         updated_at?: string;
         alternative_id?: components["schemas"]["AlternativeIdentifier"];
     }>;
+    /**
+     * Delete a customer that has no invoices. Its NIF (or alternative id) is released for a
+     * new customer.
+     *
+     * @param customerId - Customer UUID.
+     */
     delete(customerId: string): Promise<void>;
 }
-/** Products addressed per company. */
+/** Products and services of one company. Reach it as `beel.company(companyId).products`. */
 declare class CompanyProductsResource {
     private client;
     private companyId;
     constructor(client: BeeLClient, companyId: string);
+    /**
+     * List the company's products, paginated and searchable.
+     *
+     * @param params - Filters and pagination.
+     * @returns The page of `products` and its `pagination`.
+     */
     list(params?: operations['listCompanyProducts']['parameters']['query']): Promise<{
         products: Product[];
         pagination: Pagination;
     }>;
+    /**
+     * Create a product or service.
+     *
+     * @param body - Name, category, price and main tax.
+     * @returns The created product.
+     */
     create(body: components['schemas']['CreateProductRequest']): Promise<{
         id: string;
         code?: string | null;
@@ -33960,6 +34860,12 @@ declare class CompanyProductsResource {
         created_at: string;
         updated_at: string;
     }>;
+    /**
+     * Get one product.
+     *
+     * @param productId - Product UUID.
+     * @returns The product.
+     */
     get(productId: string): Promise<{
         id: string;
         code?: string | null;
@@ -33975,6 +34881,13 @@ declare class CompanyProductsResource {
         created_at: string;
         updated_at: string;
     }>;
+    /**
+     * Update a product. Only the fields present in `body` change.
+     *
+     * @param productId - Product UUID.
+     * @param body - Fields to change.
+     * @returns The updated product.
+     */
     update(productId: string, body: operations['patchCompanyProduct']['requestBody']['content']['application/json']): Promise<{
         id: string;
         code?: string | null;
@@ -33990,13 +34903,27 @@ declare class CompanyProductsResource {
         created_at: string;
         updated_at: string;
     }>;
+    /**
+     * Delete a product from the catalog. Existing invoice lines are unaffected.
+     *
+     * @param productId - Product UUID.
+     */
     delete(productId: string): Promise<void>;
 }
-/** Invoice series addressed per company. */
+/**
+ * Invoice series (numbering) of one company. Each series numbers one `document_type`.
+ * Reach it as `beel.company(companyId).series`.
+ */
 declare class CompanySeriesResource {
     private client;
     private companyId;
     constructor(client: BeeLClient, companyId: string);
+    /**
+     * List the company's series.
+     *
+     * @param params - Filters; `page`/`limit` to paginate.
+     * @returns The `series`, and `pagination` when you paginated.
+     */
     list(params?: operations['listCompanySeries']['parameters']['query']): Promise<{
         series: {
             id: string;
@@ -34023,6 +34950,12 @@ declare class CompanySeriesResource {
             has_previous?: boolean | undefined;
         } | undefined;
     } | undefined>;
+    /**
+     * Create a series.
+     *
+     * @param body - Code, name, format and the `document_type` it numbers.
+     * @returns The created series.
+     */
     create(body: operations['createCompanySeries']['requestBody']['content']['application/json']): Promise<{
         id: string;
         document_type: components["schemas"]["DocumentType"];
@@ -34039,6 +34972,13 @@ declare class CompanySeriesResource {
         readonly next_number?: number | undefined;
         updated_at?: string | undefined;
     } | undefined>;
+    /**
+     * Update a series. Only the fields present in `body` change.
+     *
+     * @param seriesId - Series UUID.
+     * @param body - Fields to change.
+     * @returns The updated series.
+     */
     update(seriesId: string, body: operations['patchCompanySeries']['requestBody']['content']['application/json']): Promise<{
         id: string;
         document_type: components["schemas"]["DocumentType"];
@@ -34055,8 +34995,17 @@ declare class CompanySeriesResource {
         readonly next_number?: number | undefined;
         updated_at?: string | undefined;
     } | undefined>;
+    /**
+     * Delete (soft-delete) a series. Its code stays taken, since issued invoices carry it.
+     *
+     * @param seriesId - Series UUID.
+     */
     delete(seriesId: string): Promise<void>;
-    /** Current default series per invoice type. */
+    /**
+     * The current default series per document type.
+     *
+     * @returns One entry per document type, saying whether a default exists.
+     */
     getDefaults(): Promise<{
         defaults: {
             document_type: components["schemas"]["DocumentType"];
@@ -34066,7 +35015,12 @@ declare class CompanySeriesResource {
             provisional?: boolean | undefined;
         }[];
     } | undefined>;
-    /** 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.
+     */
     ensureDefaults(): Promise<{
         series: {
             id: string;
@@ -34085,7 +35039,12 @@ declare class CompanySeriesResource {
             updated_at?: string | undefined;
         }[];
     } | undefined>;
-    /** 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.
+     */
     setDefault(seriesId: string): Promise<{
         id: string;
         document_type: components["schemas"]["DocumentType"];
@@ -34103,12 +35062,21 @@ declare class CompanySeriesResource {
         updated_at?: string | undefined;
     } | undefined>;
 }
-/** Recurring invoices addressed per company. */
+/**
+ * Recurring invoice templates of one company. Reach it as
+ * `beel.company(companyId).recurringInvoices`.
+ */
 declare class CompanyRecurringInvoicesResource {
     private client;
     private companyId;
     constructor(client: BeeLClient, companyId: string);
     private path;
+    /**
+     * List the recurring invoices.
+     *
+     * @param params - Filters and pagination.
+     * @returns The page of `recurring_invoices` and its `pagination`.
+     */
     list(params?: operations['listCompanyRecurringInvoices']['parameters']['query']): Promise<{
         recurring_invoices: {
             id?: string | undefined;
@@ -34190,6 +35158,12 @@ declare class CompanyRecurringInvoicesResource {
             has_previous?: boolean | undefined;
         } | undefined;
     } | undefined>;
+    /**
+     * Create a recurring invoice template.
+     *
+     * @param body - Frequency, schedule, recipient and lines.
+     * @returns The recurring invoice.
+     */
     create(body: operations['createCompanyRecurringInvoice']['requestBody']['content']['application/json']): Promise<{
         id?: string | undefined;
         name?: string | undefined;
@@ -34261,6 +35235,12 @@ declare class CompanyRecurringInvoicesResource {
         created_at?: string | undefined;
         updated_at?: string | undefined;
     } | undefined>;
+    /**
+     * Get one recurring invoice.
+     *
+     * @param recurringInvoiceId - Recurring invoice UUID.
+     * @returns The recurring invoice.
+     */
     get(recurringInvoiceId: string): Promise<{
         id?: string | undefined;
         name?: string | undefined;
@@ -34332,6 +35312,13 @@ declare class CompanyRecurringInvoicesResource {
         created_at?: string | undefined;
         updated_at?: string | undefined;
     } | undefined>;
+    /**
+     * 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.
+     */
     update(recurringInvoiceId: string, body: operations['patchCompanyRecurringInvoice']['requestBody']['content']['application/json']): Promise<{
         id?: string | undefined;
         name?: string | undefined;
@@ -34403,8 +35390,20 @@ declare class CompanyRecurringInvoicesResource {
         created_at?: string | undefined;
         updated_at?: string | undefined;
     } | undefined>;
+    /**
+     * Delete a recurring invoice and cancel its pending generations. Invoices it already
+     * generated are kept.
+     *
+     * @param recurringInvoiceId - Recurring invoice UUID.
+     */
     delete(recurringInvoiceId: string): Promise<void>;
-    /** 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.
+     */
     setStatus(recurringInvoiceId: string, body: operations['setCompanyRecurringInvoiceStatus']['requestBody']['content']['application/json']): Promise<{
         id?: string | undefined;
         name?: string | undefined;
@@ -34476,7 +35475,12 @@ declare class CompanyRecurringInvoicesResource {
         created_at?: string | undefined;
         updated_at?: string | undefined;
     } | undefined>;
-    /** Skip the next scheduled occurrence. */
+    /**
+     * Skip the next scheduled occurrence.
+     *
+     * @param recurringInvoiceId - Recurring invoice UUID.
+     * @returns The recurring invoice with its next date moved.
+     */
     skip(recurringInvoiceId: string): Promise<{
         id?: string | undefined;
         name?: string | undefined;
@@ -34548,11 +35552,22 @@ declare class CompanyRecurringInvoicesResource {
         created_at?: string | undefined;
         updated_at?: string | undefined;
     } | undefined>;
-    /** 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.
+     */
     generateNow(recurringInvoiceId: string): Promise<{
         invoice_id?: string | undefined;
         next_generation?: string | null | undefined;
     } | undefined>;
+    /**
+     * Preview the next invoice the template will generate.
+     *
+     * @param recurringInvoiceId - Recurring invoice UUID.
+     * @returns The invoice as it would be generated.
+     */
     nextOccurrence(recurringInvoiceId: string): Promise<{
         invoice_number?: string | null | undefined;
         series: {
@@ -34732,6 +35747,13 @@ declare class CompanyRecurringInvoicesResource {
         } | undefined;
         deleted_at?: string | null | undefined;
     } | undefined>;
+    /**
+     * The generation history of the template: generated, skipped and failed occurrences.
+     *
+     * @param recurringInvoiceId - Recurring invoice UUID.
+     * @param params - Pagination.
+     * @returns The `history` entries.
+     */
     history(recurringInvoiceId: string, params?: operations['getCompanyRecurringInvoiceHistory']['parameters']['query']): Promise<{
         history: {
             id?: string | undefined;
@@ -34758,13 +35780,19 @@ declare class CompanyRecurringInvoicesResource {
     } | undefined>;
 }
 /**
- * Tax defaults of one company. The canonical replacement for the account-wide
- * `beel.configuration.getTaxes()`, whose flat route is deprecated.
+ * Tax defaults of one company (main tax, IRPF, equivalence surcharge). The canonical
+ * replacement for the account-wide `beel.configuration.getTaxConfig()`, whose flat route is
+ * deprecated. Reach it as `beel.company(companyId).taxConfiguration`.
  */
 declare class CompanyTaxConfigurationResource {
     private client;
     private companyId;
     constructor(client: BeeLClient, companyId: string);
+    /**
+     * Get the tax configuration.
+     *
+     * @returns The company's tax defaults.
+     */
     get(): Promise<{
         default_main_tax: {
             type: components["schemas"]["TaxType"];
@@ -34786,7 +35814,12 @@ declare class CompanyTaxConfigurationResource {
             suggested_irpf_rate: number | null;
         } | undefined;
     } | undefined>;
-    /** 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.
+     */
     update(body: components['schemas']['UpdateTaxConfigurationRequest']): Promise<{
         default_main_tax: {
             type: components["schemas"]["TaxType"];
@@ -34811,16 +35844,23 @@ declare class CompanyTaxConfigurationResource {
 }
 /**
  * VeriFactu configuration of one company. The canonical replacement for
- * `beel.configuration.getVerifactu()`, whose flat route is deprecated.
+ * `beel.configuration.getVerifactu()`, whose flat route is deprecated. Reach it as
+ * `beel.company(companyId).verifactuConfiguration`.
  *
  * Whether an invoice reaches AEAT is a fact of this NIF resolved at issue time, not a
  * per-invoice choice: `enabled` is the only writable field. Everything else — `status`,
- * `nif_status`, `signed`, `activated`, `pdf_generated` — is resolved server-side.
+ * `nif_status`, `signed`, `activated`, `pdf_generated` — is resolved server-side. The
+ * outcome of each invoice is on the invoice itself: `invoice.verifactu.submission_status`.
  */
 declare class CompanyVeriFactuConfigurationResource {
     private client;
     private companyId;
     constructor(client: BeeLClient, companyId: string);
+    /**
+     * Get the VeriFactu configuration of this NIF.
+     *
+     * @returns `enabled` and the server-resolved state of the NIF.
+     */
     get(): Promise<{
         enabled: boolean;
         nif_status?: "ACTIVATED" | "DEACTIVATED" | null | undefined;
@@ -34830,7 +35870,12 @@ declare class CompanyVeriFactuConfigurationResource {
         activated?: boolean | null | undefined;
         pdf_generated?: boolean | null | undefined;
     } | undefined>;
-    /** 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.
+     */
     update(body: components['schemas']['UpdateVeriFactuConfigurationRequest']): Promise<{
         enabled: boolean;
         nif_status?: "ACTIVATED" | "DEACTIVATED" | null | undefined;
@@ -34843,18 +35888,25 @@ declare class CompanyVeriFactuConfigurationResource {
 }
 
 /**
- * BeeL SDK Client
+ * The BeeL API client. Create one per API key and reuse it; it holds no global state.
+ * Address a company with {@link company} and an account with {@link account}.
+ *
+ * Requests are retried automatically when it is safe — see `BeeLConfig` — and every `POST`
+ * carries an `Idempotency-Key` that those retries reuse.
  *
  * @example
  * ```typescript
  * import { BeeL } from '@beel_es/sdk';
  *
- * const beel = new BeeL({ apiKey: 'beel_sk_live_...' });
+ * const beel = new BeeL({ apiKey: process.env.BEEL_API_KEY! });
  *
  * const invoice = await beel.company('company-uuid').invoices.create({
  *   type: 'STANDARD',
- *   recipient: { customer_id: 'uuid' },
- *   lines: [{ line_type: 'NORMAL', description: 'Service', quantity: 1, unit_price: 100 }],
+ *   recipient: { customer_id: 'customer-uuid' },
+ *   lines: [{
+ *     description: 'Service', quantity: 1, unit_price: 100,
+ *     main_tax: { type: 'IVA', percentage: 21, regime_key: '01' },
+ *   }],
  * });
  * ```
  */
@@ -34869,8 +35921,9 @@ declare class BeeL {
     readonly configuration: ConfigurationResource;
     /** @deprecated Session-focus endpoints are deprecated in the API contract. Use `beel.company(companyId).series` instead. */
     readonly series: SeriesResource;
-    /** Account-wide catalogs and personal preferences, on their canonical paths. */
+    /** Account-wide catalogs, the credential's identity and personal preferences. */
     readonly catalogs: CatalogsResource;
+    /** NIF validation against the AEAT register. */
     readonly nif: NifResource;
     /** Accounts you manage (multi-account provisioning: members, invitations, webhooks, companies). */
     readonly accounts: AccountsResource;
@@ -34885,7 +35938,9 @@ declare class BeeL {
      * builders) and the naming stability the wrappers provide.
      *
      * Retries, the `Authorization` header and `Idempotency-Key` still apply: it is the
-     * same client the resources use, middleware included.
+     * same client the resources use, middleware included. That includes error handling: a
+     * non-2xx answer is **thrown** as a `BeeLApiError` subclass, so `raw` calls never resolve
+     * with openapi-fetch's `{ error }`; `data` is always the successful body.
      *
      * @example
      * ```typescript
@@ -34898,7 +35953,11 @@ declare class BeeL {
     constructor(config: BeeLConfig);
     /**
      * 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
@@ -34908,8 +35967,12 @@ declare class BeeL {
      */
     company(companyId: string): CompanyScope;
     /**
-     * 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
@@ -34924,6 +35987,10 @@ declare class BeeL {
      * @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');
@@ -34937,37 +36004,89 @@ declare class BeeL {
 }
 
 /**
- * Base error for all BeeL API errors.
+ * Base error for every non-2xx answer of the BeeL API. The client throws it (or one of its
+ * subclasses) from any resource method; a network failure is thrown as the platform's own
+ * `fetch` error instead.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await company.invoices.issue(invoiceId);
+ * } catch (error) {
+ *   if (error instanceof BeeLApiError) console.error(error.statusCode, error.apiCode, error.requestId);
+ *   throw error;
+ * }
+ * ```
  */
 declare class BeeLApiError extends Error {
+    /** HTTP status of the response. */
     readonly statusCode: number;
+    /**
+     * Stable code of the error class. On the base class it is the API's `error.code`; the
+     * subclasses keep a fixed generic value (`CONFLICT`, `NOT_FOUND`…) for backward
+     * compatibility. Read {@link apiCode} for the API's specific code.
+     */
     readonly code: string;
+    /**
+     * The `error.code` the API answered with, verbatim — for example
+     * `INVOICE_DUPLICATE_EXTERNAL_REFERENCE`. Equal to {@link code} when the response did not
+     * carry one. See {@link BeeLErrorCodes} for the codes this SDK reacts to.
+     */
+    readonly apiCode: string;
+    /** `error.details` of the response, when the API sent any. */
     readonly details?: Record<string, string>;
+    /** `meta.request_id` of the response. Quote it when you contact support. */
     readonly requestId?: string;
-    constructor(message: string, statusCode: number, code: string, details?: Record<string, string>, requestId?: string);
+    constructor(message: string, statusCode: number, code: string, details?: Record<string, string>, requestId?: string, apiCode?: string);
 }
-/** 429 — Rate limit exceeded */
+/** `429`: rate limit exceeded. Retried automatically, see `maxRetries`. */
 declare class BeeLRateLimitError extends BeeLApiError {
+    /** Seconds the API asked to wait before the next request. */
     readonly retryAfterSeconds: number;
-    constructor(message: string, retryAfterSeconds: number, requestId?: string);
+    constructor(message: string, retryAfterSeconds: number, requestId?: string, apiCode?: string);
 }
-/** 422 — Validation or business rule error */
+/** `422`: validation or business rule error. `details` names the offending fields. */
 declare class BeeLValidationError extends BeeLApiError {
-    constructor(message: string, details?: Record<string, string>, requestId?: string);
+    constructor(message: string, details?: Record<string, string>, requestId?: string, apiCode?: string);
 }
-/** 401 / 403 — Authentication or authorization error */
+/** `401` / `403`: the API key is missing or invalid, or lacks access to the resource. */
 declare class BeeLAuthError extends BeeLApiError {
-    constructor(message: string, statusCode: 401 | 403, requestId?: string);
+    constructor(message: string, statusCode: 401 | 403, requestId?: string, apiCode?: string);
 }
-/** 404 — Resource not found */
+/** `404`: the resource does not exist. */
 declare class BeeLNotFoundError extends BeeLApiError {
-    constructor(message: string, requestId?: string);
+    constructor(message: string, requestId?: string, apiCode?: string);
 }
-/** 409 — Conflict (e.g. duplicate resource) */
+/**
+ * `409`: conflict — for example `INVOICE_DUPLICATE_EXTERNAL_REFERENCE` or an
+ * `Idempotency-Key` reused with another body. Branch on {@link BeeLApiError.apiCode}.
+ */
 declare class BeeLConflictError extends BeeLApiError {
-    constructor(message: string, requestId?: string);
+    constructor(message: string, requestId?: string, apiCode?: string, details?: Record<string, string>);
 }
 
+/**
+ * `error.code` values of the API that the SDK itself reacts to. Compare them with
+ * {@link BeeLApiError.apiCode}. The full catalogue lives in the API reference
+ * (https://docs.beel.es); these are the ones this package has behaviour for.
+ */
+declare const 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 })`.
+     */
+    readonly 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.
+     */
+    readonly IDEMPOTENCY_KEY_PROCESSING: "IDEMPOTENCY_KEY_PROCESSING";
+    /** `409`: the `Idempotency-Key` was already used with a different body. Use a new key. */
+    readonly IDEMPOTENCY_KEY_MISMATCH: "IDEMPOTENCY_KEY_MISMATCH";
+};
+/** One of the {@link BeeLErrorCodes} values. */
+type BeeLErrorCode = (typeof BeeLErrorCodes)[keyof typeof BeeLErrorCodes];
+
 type WebhookEventDataAccountBase = {
     /**
      * The provisioned account this event refers to.
@@ -35375,7 +36494,7 @@ type WebhookEventDataTest = {
  * @example Express.js
  * ```typescript
  * import express from 'express';
- * import { WebhookVerifier } from '@beel/sdk';
+ * import { WebhookVerifier } from '@beel_es/sdk';
  *
  * const verifier = new WebhookVerifier('your_webhook_secret');
  *
@@ -35470,15 +36589,25 @@ type BusinessEvent<K extends `${WebhookEventType}`, D> = Omit<WebhookEventEnvelo
     test?: false | null;
     data: D;
 };
+/** `verifactu.status.updated`: AEAT answered for an invoice's VeriFactu record (`new_status`, `qr_url`…). */
 type VeriFactuStatusUpdatedEvent = BusinessEvent<'verifactu.status.updated', WebhookEventDataVeriFactuStatusUpdated>;
+/** `invoice.issued`: an invoice was issued. */
 type InvoiceIssuedEvent = BusinessEvent<'invoice.issued', WebhookEventDataInvoiceIssued>;
+/** `invoice.voided`: an invoice was voided. */
 type InvoiceVoidedEvent = BusinessEvent<'invoice.voided', WebhookEventDataInvoiceVoided>;
+/** `invoice.email.sent`: an invoice email was accepted by the email provider. */
 type InvoiceEmailSentEvent = BusinessEvent<'invoice.email.sent', WebhookEventDataInvoiceEmailSent>;
+/** `invoice.pdf.generated`: the PDF of an invoice is ready. */
 type InvoicePdfGeneratedEvent = BusinessEvent<'invoice.pdf.generated', WebhookEventDataInvoicePdfGenerated>;
+/** `invoice.schedule_failed`: a scheduled invoice could not be processed. */
 type InvoiceScheduleFailedEvent = BusinessEvent<'invoice.schedule_failed', WebhookEventDataInvoiceScheduleFailed>;
+/** `recurring_invoice.paused`: a recurring invoice was paused. */
 type RecurringInvoicePausedEvent = BusinessEvent<'recurring_invoice.paused', WebhookEventDataRecurringInvoicePaused>;
+/** `account.claimed`: the holder of a provisioned account took ownership. */
 type AccountClaimedEvent = BusinessEvent<'account.claimed', WebhookEventDataAccountClaimed>;
+/** `company.created`: a company (NIF) was created. */
 type CompanyCreatedEvent = BusinessEvent<'company.created', WebhookEventDataCompanyCreated>;
+/** `representation.signed`: a representation document was signed. */
 type RepresentationSignedEvent = BusinessEvent<'representation.signed', WebhookEventDataRepresentationSigned>;
 /**
  * A delivery sent with "Send test": `test` is `true` and `data` is a synthetic message,
@@ -35496,7 +36625,8 @@ type WebhookEvent = VeriFactuStatusUpdatedEvent | InvoiceIssuedEvent | InvoiceVo
 
 type CreateCustomerRequest = components['schemas']['CreateCustomerRequest'];
 /**
- * Fluent builder for creating customers with a clean, readable API.
+ * Fluent builder for the body of `customers.create`. It builds the request object only;
+ * send it with `beel.company(companyId).customers.create(builder.build())`.
  *
  * @example
  * ```typescript
@@ -35516,28 +36646,88 @@ declare class CustomerBuilder {
     private _address?;
     private _notes?;
     private constructor();
+    /**
+     * Start a new builder.
+     *
+     * @returns An empty customer builder.
+     */
     static create(): CustomerBuilder;
+    /**
+     * Legal name of the customer. Required.
+     *
+     * @param name - Legal name.
+     * @returns This builder.
+     */
     name(name: string): this;
+    /**
+     * NIF/CIF of the customer. Required.
+     *
+     * @param nif - Spanish tax id.
+     * @returns This builder.
+     */
     nif(nif: string): this;
+    /**
+     * Contact email.
+     *
+     * @param email - Email address.
+     * @returns This builder.
+     */
     email(email: string): this;
+    /**
+     * Contact phone: 9 to 20 characters of digits, spaces, dashes, parentheses and a leading `+`.
+     *
+     * @param phone - Phone number.
+     * @returns This builder.
+     */
     phone(phone: string): 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: string, number: string, postalCode: string, city: string, province: string, country: string, countryCode?: string): this;
+    /**
+     * Internal notes about the customer.
+     *
+     * @param notes - Free text.
+     * @returns This builder.
+     */
     notes(notes: string): this;
+    /**
+     * Build the request body.
+     *
+     * @returns The `CreateCustomerRequest`.
+     * @throws {Error} When the name, NIF or address is missing.
+     */
     build(): CreateCustomerRequest;
 }
 
 type CreateInvoiceRequest = components['schemas']['CreateInvoiceRequest'];
 type InvoiceType = components['schemas']['InvoiceType'];
 type InvoiceLine = CreateInvoiceRequest['lines'][number];
+type LineMainTax = NonNullable<InvoiceLine['main_tax']>;
 /**
- * Fluent builder for creating invoices with a clean, readable API.
+ * Fluent builder for the body of `invoices.create`. It builds the request object only; send
+ * it with `beel.company(companyId).invoices.create(builder.build())`.
+ *
+ * The API requires a `main_tax` on every `NORMAL` line (`422 LINE_MAIN_TAX_REQUIRED`
+ * otherwise): set it once with {@link mainTax}, or per line in {@link addLine}.
  *
  * @example
  * ```typescript
- * const invoice = InvoiceBuilder.create()
+ * const request = InvoiceBuilder.create()
  *   .forCustomer('customer-uuid')
- *   .addLine('Consulting services', 10, 85.50)
+ *   .mainTax({ type: 'IVA', percentage: 21, regime_key: '01' })
+ *   .addLine('Consulting services', 10, 85.5)
  *   .build();
+ * const invoice = await beel.company(companyId).invoices.create(request);
  * ```
  */
 declare class InvoiceBuilder {
@@ -35549,17 +36739,96 @@ declare class InvoiceBuilder {
     private _notes?;
     private _seriesId?;
     private _metadata?;
+    private _mainTax?;
     private constructor();
+    /**
+     * Start a new builder.
+     *
+     * @returns An empty `STANDARD` invoice builder.
+     */
     static create(): InvoiceBuilder;
+    /**
+     * Set the invoice type. Default: `STANDARD`.
+     *
+     * @param type - `STANDARD`, `SIMPLIFIED` or `PROFORMA` (correctives use `createCorrective`).
+     * @returns This builder.
+     */
     type(type: InvoiceType): this;
+    /**
+     * Invoice a registered customer.
+     *
+     * @param customerId - Customer UUID.
+     * @returns This builder.
+     */
     forCustomer(customerId: string): 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: string | Date): this;
+    /**
+     * Payment due date.
+     *
+     * @param date - A `Date` or a `YYYY-MM-DD` string.
+     * @returns This builder.
+     */
     dueDate(date: string | Date): this;
-    addLine(description: string, quantity: number, unitPrice: number, discountPercentage?: number): this;
+    /**
+     * 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: LineMainTax): 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: string, quantity: number, unitPrice: number, discountPercentage?: number, mainTax?: LineMainTax): this;
+    /**
+     * Add a line exactly as given — any line type or pricing mode.
+     *
+     * @param line - A line of `CreateInvoiceRequest`.
+     * @returns This builder.
+     */
     addLineObject(line: InvoiceLine): this;
+    /**
+     * Notes printed on the invoice.
+     *
+     * @param notes - Free text.
+     * @returns This builder.
+     */
     notes(notes: string): this;
+    /**
+     * Number the invoice in this series instead of the default one.
+     *
+     * @param id - Series UUID.
+     * @returns This builder.
+     */
     series(id: string): this;
+    /**
+     * Your own key/value pairs, filterable when listing.
+     *
+     * @param data - Metadata to store with the invoice.
+     * @returns This builder.
+     */
     metadata(data: Record<string, any>): this;
+    /**
+     * Build the request body.
+     *
+     * @returns The `CreateInvoiceRequest`.
+     * @throws {Error} When there is no customer or no line.
+     */
     build(): CreateInvoiceRequest;
 }
 
@@ -35568,4 +36837,4 @@ type VeriFactuStatusUpdatedData = WebhookEventDataVeriFactuStatusUpdated;
 /** @deprecated Renamed in the contract — use `VeriFactuSubmissionStatus`. */
 type VeriFactuStatus = VeriFactuSubmissionStatus;
 
-export { type AccountClaimedEvent, AccountCompaniesResource, AccountInvitationsResource, AccountMembersResource, AccountScope, AccountWebhooksResource, AccountsResource, BeeL, BeeLApiError, BeeLAuthError, type BeeLConfig, BeeLConflictError, BeeLNotFoundError, BeeLRateLimitError, BeeLValidationError, CatalogsResource, type CompanyCreatedEvent, CompanyCustomersResource, CompanyInvoiceScheduleResource, CompanyInvoicesResource, CompanyPaymentConnectionsResource, CompanyPaymentEventsResource, CompanyProductsResource, CompanyRecurringInvoicesResource, CompanyScope, CompanySeriesResource, CompanyTaxConfigurationResource, CompanyVeriFactuConfigurationResource, CustomerBuilder, InvoiceBuilder, type InvoiceEmailSentEvent, type InvoiceIssuedEvent, type InvoicePdfGeneratedEvent, type InvoiceScheduleFailedEvent, type InvoiceVoidedEvent, type RecurringInvoicePausedEvent, type RepresentationSignedEvent, type VeriFactuStatus, type VeriFactuStatusUpdatedData, type VeriFactuStatusUpdatedEvent, VeriFactuSubmissionStatus, type WebhookEvent, type WebhookEventDataAccountClaimed, type WebhookEventDataCompanyCreated, type WebhookEventDataInvoiceEmailSent, type WebhookEventDataInvoiceIssued, type WebhookEventDataInvoicePdfGenerated, type WebhookEventDataInvoiceScheduleFailed, type WebhookEventDataInvoiceVoided, type WebhookEventDataRecurringInvoicePaused, type WebhookEventDataRepresentationSigned, type WebhookEventDataTest, type WebhookEventDataVeriFactuStatusUpdated, type WebhookEventEnvelope, WebhookEventType, type WebhookTestEvent, WebhookVerificationError, WebhookVerifier, type components, type operations, type paths };
+export { type AccountClaimedEvent, AccountCompaniesResource, AccountInvitationsResource, AccountMembersResource, AccountScope, AccountWebhooksResource, AccountsResource, BeeL, BeeLApiError, BeeLAuthError, type BeeLConfig, BeeLConflictError, type BeeLErrorCode, BeeLErrorCodes, BeeLNotFoundError, BeeLRateLimitError, BeeLValidationError, CatalogsResource, type CompanyCreatedEvent, CompanyCustomersResource, CompanyInvoiceScheduleResource, CompanyInvoicesResource, CompanyPaymentConnectionsResource, CompanyPaymentEventsResource, CompanyProductsResource, CompanyRecurringInvoicesResource, CompanyScope, CompanySeriesResource, CompanyTaxConfigurationResource, CompanyVeriFactuConfigurationResource, type CreateInvoiceOnceParams, type CreateInvoiceOnceRequest, CustomerBuilder, EXTERNAL_REF_UNIQUE_INVOICE_TYPES, type ExternalRefUniqueInvoiceType, InvoiceBuilder, type InvoiceEmailSentEvent, type InvoiceIssuedEvent, type InvoicePdfGeneratedEvent, type InvoiceScheduleFailedEvent, type InvoiceVoidedEvent, type RecurringInvoicePausedEvent, type RepresentationSignedEvent, type RequestOptions, type VeriFactuStatus, type VeriFactuStatusUpdatedData, type VeriFactuStatusUpdatedEvent, VeriFactuSubmissionStatus, type WebhookEvent, type WebhookEventDataAccountClaimed, type WebhookEventDataCompanyCreated, type WebhookEventDataInvoiceEmailSent, type WebhookEventDataInvoiceIssued, type WebhookEventDataInvoicePdfGenerated, type WebhookEventDataInvoiceScheduleFailed, type WebhookEventDataInvoiceVoided, type WebhookEventDataRecurringInvoicePaused, type WebhookEventDataRepresentationSigned, type WebhookEventDataTest, type WebhookEventDataVeriFactuStatusUpdated, type WebhookEventEnvelope, WebhookEventType, type WebhookTestEvent, WebhookVerificationError, WebhookVerifier, type components, type operations, type paths };