@beel_es/sdk 2.5.0 → 2.6.0

package/docs/reference/README.md

@@ -36,6 +36,7 @@ Start with the [README](../../README.md) for setup and common tasks.
 | [`CatalogsResource`](catalogs.md) | `beel.catalogs` | Account-wide catalogs, the credential's identity and personal preferences, on their canonical paths. |
 | [`CompanyScope`](company.md) | `beel.company(companyId)` | Operations scoped to a single company (NIF). |
 | [`CompanyCustomersResource`](company-customers.md) | `beel.company(companyId).customers` | Customers of one company. |
+| [`CompanyInvoiceRepliesResource`](company-invoice-replies.md) | `beel.company(companyId).invoiceReplies` | Replies of the customers of a company about its invoices, on any channel. |
 | [`CompanyInvoicesResource`](company-invoices.md) | `beel.company(companyId).invoices` | Invoice lifecycle of one company: create a draft (or issue it directly), issue, void, correct, list and read, PDF and email. |
 | [`CompanyInvoiceScheduleResource`](company-invoices-schedule.md) | `beel.company(companyId).invoices.schedule` | Scheduled issuing of one invoice: read it, set it, clear it. |
 | [`CompanyPaymentConnectionsResource`](company-payment-connections.md) | `beel.company(companyId).paymentConnections` | Payment connections of a company (NIF): the Stripe Connect link whose charges auto-generate invoices under that NIF. |
@@ -112,6 +113,11 @@ Start with the [README](../../README.md) for setup and common tasks.
 | [`beel.company(companyId).customers.get(customerId)`](company-customers.md#company-customers-get) | `GET /v1/companies/{company_id}/customers/{customer_id}` | Get one customer. |
 | [`beel.company(companyId).customers.update(customerId, body)`](company-customers.md#company-customers-update) | `PATCH /v1/companies/{company_id}/customers/{customer_id}` | Update a customer. |
 | [`beel.company(companyId).customers.delete(customerId)`](company-customers.md#company-customers-delete) | `DELETE /v1/companies/{company_id}/customers/{customer_id}` | Delete a customer that has no invoices. |
+| [`beel.company(companyId).invoiceReplies.list(params?, options?)`](company-invoice-replies.md#company-invoice-replies-list) | `GET /v1/companies/{company_id}/invoice-replies` | List the replies of the company, most recent first, with masked `excerpt`, `subject` and sender. |
+| [`beel.company(companyId).invoiceReplies.create(body, options?)`](company-invoice-replies.md#company-invoice-replies-create) | `POST /v1/companies/{company_id}/invoice-replies` | Register a message that a customer sent you on a channel of your own about an invoice. |
+| [`beel.company(companyId).invoiceReplies.get(replyId, options?)`](company-invoice-replies.md#company-invoice-replies-get) | `GET /v1/companies/{company_id}/invoice-replies/{reply_id}` | Get one reply with its full text and the file names of its attachments. |
+| [`beel.company(companyId).invoiceReplies.delete(replyId, options?)`](company-invoice-replies.md#company-invoice-replies-delete) | `DELETE /v1/companies/{company_id}/invoice-replies/{reply_id}` | Delete a reply: its content is erased. |
+| [`beel.company(companyId).invoiceReplies.getAttachment(replyId, attachmentId, options?)`](company-invoice-replies.md#company-invoice-replies-get-attachment) | `GET /v1/companies/{company_id}/invoice-replies/{reply_id}/attachments/{attachment_id}` | Get an attachment of a reply with a temporary `download_url` for its file. |
 | [`beel.company(companyId).invoices.derive(body, options?)`](company-invoices.md#company-invoices-derive) | `POST /v1/companies/{company_id}/invoices/derivations` | Derive a new draft invoice from an existing one — the canonical form of `duplicate`. |
 | [`beel.company(companyId).invoices.list(params?, options?)`](company-invoices.md#company-invoices-list) | `GET /v1/companies/{company_id}/invoices` | List the company's invoices, paginated, with filters: status, type, customer, dates, `external_ref` (exact match), VeriFactu status and more. |
 | [`beel.company(companyId).invoices.create(body, params?, options?)`](company-invoices.md#company-invoices-create) | `POST /v1/companies/{company_id}/invoices` | Create an invoice: a `DRAFT` by default, or numbered and issued in the same call with `options.issue_directly: true`. |

package/docs/reference/company-invoice-replies.md

@@ -0,0 +1,122 @@
+<!-- Generated by `npm run docs:reference` from the SDK source and openapi/public-api.yaml. Do not edit. -->
+
+# `beel.company(companyId).invoiceReplies` — `CompanyInvoiceRepliesResource`
+
+[Reference index](README.md)
+
+Replies of the customers of a company about its invoices, on any channel. Reach it as
+`beel.company(companyId).invoiceReplies`.
+
+The list masks personal data; `get` returns the full text. An attachment is read
+with `getAttachment`, which returns a temporary download link for its file.
+
+**Example**
+
+```typescript
+const replies = beel.company('company-uuid').invoiceReplies;
+const { replies: page } = await replies.list({ invoice_id: 'invoice-uuid' });
+const reply = await replies.get(page[0].id);
+const attachment = await replies.getAttachment(reply.id, reply.attachments![0].id);
+if (attachment.download_url) console.log(attachment.download_url);
+```
+
+## Methods
+
+| Method | HTTP | Summary |
+|---|---|---|
+| [`beel.company(companyId).invoiceReplies.list(params?, options?)`](#company-invoice-replies-list) | `GET /v1/companies/{company_id}/invoice-replies` | List the replies of the company, most recent first, with masked `excerpt`, `subject` and sender. |
+| [`beel.company(companyId).invoiceReplies.create(body, options?)`](#company-invoice-replies-create) | `POST /v1/companies/{company_id}/invoice-replies` | Register a message that a customer sent you on a channel of your own about an invoice. |
+| [`beel.company(companyId).invoiceReplies.get(replyId, options?)`](#company-invoice-replies-get) | `GET /v1/companies/{company_id}/invoice-replies/{reply_id}` | Get one reply with its full text and the file names of its attachments. |
+| [`beel.company(companyId).invoiceReplies.delete(replyId, options?)`](#company-invoice-replies-delete) | `DELETE /v1/companies/{company_id}/invoice-replies/{reply_id}` | Delete a reply: its content is erased. |
+| [`beel.company(companyId).invoiceReplies.getAttachment(replyId, attachmentId, options?)`](#company-invoice-replies-get-attachment) | `GET /v1/companies/{company_id}/invoice-replies/{reply_id}/attachments/{attachment_id}` | Get an attachment of a reply with a temporary `download_url` for its file. |
+
+<a id="company-invoice-replies-list"></a>
+### `list(params?, options?)`
+
+List the replies of the company, most recent first, with masked `excerpt`, `subject`
+and sender.
+
+- **HTTP:** `GET /v1/companies/{company_id}/invoice-replies` · operation `listCompanyInvoiceReplies` · scopes `invoice-replies:read`
+- **Parameters:**
+  - `params?: operations['listCompanyInvoiceReplies']['parameters']['query']` — Filters (`invoice_id`, `customer_id`, `channel`, `from`, `to`…) and pagination.
+  - `options?: RequestOptions` — Per-call `idempotencyKey`, `signal` and `timeoutMs`. See [`RequestOptions`](types.md#requestoptions).
+- **Returns:** The page of `replies` and its `pagination`. Response `200` `data`: `{ replies: InvoiceReplySummary[]; pagination: Pagination }`.
+- **Throws:** `400`/`500` `BeeLApiError` · `401`/`403` `BeeLAuthError` · `422` `BeeLValidationError` · `429` `BeeLRateLimitError`
+
+**Example**
+
+```typescript
+const { replies } = await company.invoiceReplies.list({ invoice_id: 'invoice-uuid' });
+```
+
+<a id="company-invoice-replies-create"></a>
+### `create(body, options?)`
+
+Register a message that a customer sent you on a channel of your own about an invoice.
+
+- **HTTP:** `POST /v1/companies/{company_id}/invoice-replies` · operation `createCompanyInvoiceReply` · scopes `invoice-replies:write` · accepts `Idempotency-Key`
+- **Parameters:**
+  - `body: components['schemas']['CreateInvoiceReplyRequest']` — The invoice, `channel`, `external_id`, sender and the text or attachments.
+  - `options?: RequestOptions` — Per-call `idempotencyKey`, `signal` and `timeoutMs`. See [`RequestOptions`](types.md#requestoptions).
+- **Returns:** The registered reply. Response `201` `data`: `InvoiceReply`.
+- **Throws:** `400`/`500` `BeeLApiError` · `401`/`403` `BeeLAuthError` · `404` `BeeLNotFoundError` · `409` `BeeLConflictError` · `422` `BeeLValidationError` · `429` `BeeLRateLimitError`
+
+**Example**
+
+```typescript
+await company.invoiceReplies.create({
+  invoice_id: 'invoice-uuid',
+  channel: 'WHATSAPP',
+  external_id: 'wamid.EXAMPLE0001',
+  sender: { address: '+34600123456' },
+  text: 'Can you send it to Distribuciones Ejemplo S.L.?',
+});
+```
+
+<a id="company-invoice-replies-get"></a>
+### `get(replyId, options?)`
+
+Get one reply with its full text and the file names of its attachments.
+
+- **HTTP:** `GET /v1/companies/{company_id}/invoice-replies/{reply_id}` · operation `getCompanyInvoiceReply` · scopes `invoice-replies:read`
+- **Parameters:**
+  - `replyId: string` — Reply UUID, from `list`.
+  - `options?: RequestOptions` — Per-call `idempotencyKey`, `signal` and `timeoutMs`. See [`RequestOptions`](types.md#requestoptions).
+- **Returns:** The reply. Response `200` `data`: `InvoiceReply`.
+- **Throws:** `401`/`403` `BeeLAuthError` · `404` `BeeLNotFoundError` · `429` `BeeLRateLimitError` · `500` `BeeLApiError`
+
+<a id="company-invoice-replies-delete"></a>
+### `delete(replyId, options?)`
+
+Delete a reply: its content is erased. Deleting it again also succeeds.
+
+- **HTTP:** `DELETE /v1/companies/{company_id}/invoice-replies/{reply_id}` · operation `deleteCompanyInvoiceReply` · scopes `invoice-replies:write`
+- **Parameters:**
+  - `replyId: string` — Reply UUID.
+  - `options?: RequestOptions` — Per-call `idempotencyKey`, `signal` and `timeoutMs`. See [`RequestOptions`](types.md#requestoptions).
+- **Returns:** `Promise<void>`
+- **Throws:** `401`/`403` `BeeLAuthError` · `404` `BeeLNotFoundError` · `429` `BeeLRateLimitError` · `500` `BeeLApiError`
+
+<a id="company-invoice-replies-get-attachment"></a>
+### `getAttachment(replyId, attachmentId, options?)`
+
+Get an attachment of a reply with a temporary `download_url` for its file. The link is
+requested on each call and expires at `download_url_expires_at`: call again for a fresh
+one rather than storing it. Both are `null` when there is no file to download.
+
+- **HTTP:** `GET /v1/companies/{company_id}/invoice-replies/{reply_id}/attachments/{attachment_id}` · operation `getCompanyInvoiceReplyAttachment` · scopes `invoice-replies:read`
+- **Parameters:**
+  - `replyId: string` — Reply UUID.
+  - `attachmentId: string` — Attachment UUID, from the `attachments` of the reply.
+  - `options?: RequestOptions` — Per-call `idempotencyKey`, `signal` and `timeoutMs`. See [`RequestOptions`](types.md#requestoptions).
+- **Returns:** The attachment, with `download_url` and `download_url_expires_at`. Response `200` `data`: `InvoiceReplyAttachmentDetail`.
+- **Throws:** `401`/`403` `BeeLAuthError` · `404` `BeeLNotFoundError` · `429` `BeeLRateLimitError` · `500`/`502` `BeeLApiError`
+
+**Example**
+
+```typescript
+const attachment = await company.invoiceReplies.getAttachment(replyId, attachmentId);
+if (attachment.download_url) {
+  const file = await fetch(attachment.download_url);
+}
+```

package/docs/reference/company.md

@@ -29,6 +29,7 @@ await company.invoices.issue(invoice.id);
 | `series` | [`CompanySeriesResource`](company-series.md) | Invoice series (numbering) of this company. |
 | `recurringInvoices` | [`CompanyRecurringInvoicesResource`](company-recurring-invoices.md) | Recurring invoice templates of this company. |
 | `paymentConnections` | [`CompanyPaymentConnectionsResource`](company-payment-connections.md) | Payment provider connections (Stripe) that auto-generate invoices under this NIF. |
+| `invoiceReplies` | [`CompanyInvoiceRepliesResource`](company-invoice-replies.md) | Replies of the customers of this company about its invoices, and their attachments. |
 | `taxConfiguration` | [`CompanyTaxConfigurationResource`](company-tax-configuration.md) | Default taxes of this company. |
 | `verifactuConfiguration` | [`CompanyVeriFactuConfigurationResource`](company-verifactu-configuration.md) | Whether this NIF submits its invoices to AEAT under VeriFactu. |
 

package/docs/reference/types.md

@@ -71,7 +71,7 @@ type BeeLErrorCode = (typeof BeeLErrorCodes)[keyof typeof BeeLErrorCodes]
 Union type of all possible webhook events
 
 ```typescript
-type WebhookEvent = | VeriFactuStatusUpdatedEvent | InvoiceIssuedEvent | InvoiceVoidedEvent | InvoiceEmailSentEvent | InvoicePdfGeneratedEvent | InvoiceScheduleFailedEvent | RecurringInvoicePausedEvent | AccountClaimedEvent | CompanyCreatedEvent | RepresentationSignedEvent | WebhookTestEvent
+type WebhookEvent = | VeriFactuStatusUpdatedEvent | InvoiceIssuedEvent | InvoiceVoidedEvent | InvoiceEmailSentEvent | InvoicePdfGeneratedEvent | InvoiceScheduleFailedEvent | RecurringInvoicePausedEvent | AccountClaimedEvent | CompanyCreatedEvent | RepresentationSignedEvent | InvoiceReplyReceivedEvent | InvoiceReplyDeletedEvent | WebhookTestEvent
 ```
 
 <a id="webhookeventenvelope"></a>
@@ -173,6 +173,24 @@ type CompanyCreatedEvent = BusinessEvent<'company.created', WebhookEventDataComp
 type RepresentationSignedEvent = BusinessEvent<'representation.signed', WebhookEventDataRepresentationSigned>
 ```
 
+<a id="invoicereplyreceivedevent"></a>
+## `InvoiceReplyReceivedEvent`
+
+`invoice.reply.received`: a customer replied about an invoice; the full reply is read with `invoiceReplies.get`.
+
+```typescript
+type InvoiceReplyReceivedEvent = BusinessEvent<'invoice.reply.received', WebhookEventDataInvoiceReplyReceived>
+```
+
+<a id="invoicereplydeletedevent"></a>
+## `InvoiceReplyDeletedEvent`
+
+`invoice.reply.deleted`: a reply was deleted; it carries identifiers only.
+
+```typescript
+type InvoiceReplyDeletedEvent = BusinessEvent<'invoice.reply.deleted', WebhookEventDataInvoiceReplyDeleted>
+```
+
 <a id="webhooktestevent"></a>
 ## `WebhookTestEvent`
 

package/llms.txt

@@ -30,6 +30,7 @@
 - [beel.catalogs](docs/reference/catalogs.md): Account-wide catalogs, the credential's identity and personal preferences, on their canonical paths.
 - [beel.company(companyId)](docs/reference/company.md): Operations scoped to a single company (NIF).
 - [beel.company(companyId).customers](docs/reference/company-customers.md): Customers of one company.
+- [beel.company(companyId).invoiceReplies](docs/reference/company-invoice-replies.md): Replies of the customers of a company about its invoices, on any channel.
 - [beel.company(companyId).invoices](docs/reference/company-invoices.md): Invoice lifecycle of one company: create a draft (or issue it directly), issue, void, correct, list and read, PDF and email.
 - [beel.company(companyId).invoices.schedule](docs/reference/company-invoices-schedule.md): Scheduled issuing of one invoice: read it, set it, clear it.
 - [beel.company(companyId).paymentConnections](docs/reference/company-payment-connections.md): Payment connections of a company (NIF): the Stripe Connect link whose charges auto-generate invoices under that NIF.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@beel_es/sdk",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "description": "Official Node.js SDK for BeeL Public API - Spanish invoicing platform with VeriFactu support",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",