sdx-mailer-sdk 1.0.19 → 1.0.21

package/README.MD

@@ -1,6 +1,266 @@
-Para publicar el package se debe actualizar la version en el package.json y luego
+# sdx-mailer-sdk
 
-1 - npm login
-2 - npm publish 
+Official Softdirex SDK for integrating with the **SDX Mailer API**. Provides typed request builders and send methods for all supported email flows: courier messages, customer lifecycle emails, and payment notifications.
 
-IMPORTANTE: No publicar endpoints ya que este package aun es publico
+## Installation
+
+```bash
+npm install sdx-mailer-sdk
+```
+
+## Usage
+
+All flows follow the same two-step pattern:
+
+1. **Build** the request with a `create*` function
+2. **Sign** it (set a `trx` field) and **send** it with the corresponding `send*` function
+
+```js
+const {
+    createCustomerMailerRequest,
+    sendMailRegister
+} = require('sdx-mailer-sdk');
+
+const request = createCustomerMailerRequest(
+    'user@example.com',   // user
+    'SecurePass1',        // password
+    'MyProduct',          // product
+    'verify-token-abc',   // token
+    'support@myapp.com'   // reply_mail
+);
+
+request.trx = yourSigningFunction(request); // request must be signed before sending
+
+const result = await sendMailRegister(
+    'Basic dXNlcjpwYXNz',       // basicAuth
+    'https://mailer.myapp.com', // endpoint
+    request
+);
+```
+
+## API Reference
+
+### Courier
+
+Generic emails with an optional call-to-action button.
+
+---
+
+#### `createCourierRequest(title, subject, message, receiver, reply_mail, btn_label, btn_link)`
+
+Builds a `CourierRequest` payload.
+
+| Parameter | Type | Description |
+|---|---|---|
+| `title` | `string` | Header title displayed in the email template |
+| `subject` | `string` | Subject line of the email |
+| `message` | `string` | Main body content |
+| `receiver` | `string` | Recipient email address |
+| `reply_mail` | `string` | Reply-to email address |
+| `btn_label` | `string \| null` | Label for the optional action button |
+| `btn_link` | `string \| null` | URL for the optional action button |
+
+Returns: `CourierRequest`
+
+---
+
+#### `createCourierExceptionRequest(error, detail, context)`
+
+Builds a `CourierExceptionRequest` payload for error/exception notifications.
+
+| Parameter | Type | Description |
+|---|---|---|
+| `error` | `string` | Error name or type (e.g. `'HTTP 500'`) |
+| `detail` | `string` | Detailed error message or stack trace excerpt |
+| `context` | `string` | Context where the error occurred (e.g. service name, endpoint) |
+
+Returns: `CourierExceptionRequest`
+
+---
+
+#### `sendCourierMail(basicAuth, endpoint, tokenRQ, productId, isBasic)`
+
+Sends a courier email. The `tokenRQ` must be signed (have a `trx` field).
+
+| Parameter | Type | Description |
+|---|---|---|
+| `basicAuth` | `string \| null` | Authorization header (e.g. `'Basic dXNlcjpwYXNz'`). Pass `null` for no auth |
+| `endpoint` | `string` | Base URL of the SDX Mailer API |
+| `tokenRQ` | `CourierRequest` | Signed request payload |
+| `productId` | `number` | Numeric product identifier sent as `product-id` header |
+| `isBasic` | `boolean` | When `true`, uses the `/basic` endpoint variant |
+
+Returns: `Promise<any>`
+
+---
+
+#### `sendExceptionMail(basicAuth, endpoint, tokenRQ, productId)`
+
+Sends an exception notification email. The `tokenRQ` must be signed.
+
+| Parameter | Type | Description |
+|---|---|---|
+| `basicAuth` | `string \| null` | Authorization header. Pass `null` for no auth |
+| `endpoint` | `string` | Base URL of the SDX Mailer API |
+| `tokenRQ` | `CourierExceptionRequest` | Signed request payload |
+| `productId` | `number` | Numeric product identifier |
+
+Returns: `Promise<any>`
+
+---
+
+### Customer
+
+Emails for the customer lifecycle: registration and password management.
+
+---
+
+#### `createCustomerMailerRequest(user, password, product, token, reply_mail)`
+
+Builds a `CustomerMailerRequest` payload used by all customer `send*` methods.
+
+| Parameter | Type | Description |
+|---|---|---|
+| `user` | `string` | Username or email address of the customer |
+| `password` | `string` | Customer's password (included in registration emails) |
+| `product` | `string` | Product name shown in the email template |
+| `token` | `string` | Verification or action token (e.g. for password reset links) |
+| `reply_mail` | `string` | Reply-to email address |
+
+Returns: `CustomerMailerRequest`
+
+---
+
+#### `sendMailRegister(basicAuth, endpoint, tokenRQ)`
+
+Sends a registration welcome email to the customer.
+
+#### `sendMailRegisterByOwner(basicAuth, endpoint, tokenRQ)`
+
+Sends a registration email triggered by an owner/admin on behalf of the customer.
+
+#### `sendMailUpdatePassword(basicAuth, endpoint, tokenRQ)`
+
+Sends a "please update your password" notification email.
+
+#### `sendMailSuccessUpdatedPassword(basicAuth, endpoint, tokenRQ)`
+
+Sends a "password updated successfully" confirmation email.
+
+All four methods share the same signature:
+
+| Parameter | Type | Description |
+|---|---|---|
+| `basicAuth` | `string \| null` | Authorization header. Pass `null` for no auth |
+| `endpoint` | `string` | Base URL of the SDX Mailer API |
+| `tokenRQ` | `CustomerMailerRequest` | Signed request payload |
+
+Returns: `Promise<any>`
+
+---
+
+### Payments
+
+Payment confirmation emails.
+
+---
+
+#### `createPaymentsMailerRequest(trxId, product)`
+
+Builds a `PaymentsMailerRequest` payload.
+
+| Parameter | Type | Description |
+|---|---|---|
+| `trxId` | `string` | Transaction ID associated with the payment |
+| `product` | `string` | Product name or licence identifier |
+
+Returns: `PaymentsMailerRequest`
+
+---
+
+#### `sendMailPayment(basicAuth, endpoint, tokenRQ)`
+
+Sends a payment confirmation email. The `tokenRQ` must be signed.
+
+| Parameter | Type | Description |
+|---|---|---|
+| `basicAuth` | `string \| null` | Authorization header. Pass `null` for no auth |
+| `endpoint` | `string` | Base URL of the SDX Mailer API |
+| `tokenRQ` | `PaymentsMailerRequest` | Signed request payload |
+
+Returns: `Promise<any>`
+
+---
+
+### Custom Mail
+
+Send a fully custom HTML email with free-form content. Uses API key authentication instead of Basic auth.
+
+---
+
+#### `createCustomMailRequest(subject, email, content, cc?)`
+
+Builds a `CustomMailRequest` payload.
+
+| Parameter | Type | Description |
+|---|---|---|
+| `subject` | `string` | Subject line of the email |
+| `email` | `string` | Recipient email address |
+| `content` | `string` | Full HTML content of the email body |
+| `cc` | `string[]` (optional) | List of CC email addresses |
+
+Returns: `CustomMailRequest`
+
+---
+
+#### `sendCustomMail(apiKey, endpoint, request)`
+
+Sends a custom HTML email. Authenticated via `x-api-key` header — no `trx` signing required.
+
+| Parameter | Type | Description |
+|---|---|---|
+| `apiKey` | `string` | API key in the format `sdx_<prefix>.<secret>`. Must have `can_execute: true` |
+| `endpoint` | `string` | Base URL of the SDX Mailer API |
+| `request` | `CustomMailRequest` | Request payload |
+
+Returns: `Promise<any>`
+
+**Example:**
+
+```js
+const { createCustomMailRequest, sendCustomMail } = require('sdx-mailer-sdk');
+
+const request = createCustomMailRequest(
+    'Welcome to our platform',
+    'user@example.com',
+    '<h1>Hello!</h1><p>Your account is ready.</p>',
+    ['manager@example.com']
+);
+
+const result = await sendCustomMail(
+    'sdx_abc123xyz.mysecret',
+    'https://mailer.myapp.com',
+    request
+);
+```
+
+---
+
+## Important notes
+
+- Courier, Customer and Payment `send*` methods throw a `WebServiceException` if the request is **not signed** (missing `trx` field) or if the API returns an error.
+- `sendCustomMail` does **not** require a `trx` field — it uses an API key instead.
+- `basicAuth` must use the format `'Basic <base64(user:password)>'` when authentication is required.
+- `productId` is sent as the `product-id` HTTP header on Courier/Customer/Payment requests.
+- API keys must follow the format `sdx_<prefix>.<secret>` and have at least one permission with `can_execute: true`.
+
+## Publishing
+
+To publish a new version update the version in `package.json`, then:
+
+```bash
+npm login
+npm publish
+```
+
+> **Important:** Do not include API endpoints, credentials, or internal configuration in the package. The `files` field in `package.json` restricts publishing to runtime-only files.

package/index.d.ts

@@ -0,0 +1,390 @@
+// Type declarations for sdx-mailer-sdk
+
+/**
+ * Represents a button/link included in a courier email.
+ */
+export interface CourierLink {
+    /** Text displayed on the action button */
+    btn_label: string;
+    /** URL the action button points to */
+    btn_link: string;
+}
+
+/**
+ * Request payload for sending a general-purpose courier email.
+ * Build this object using `createCourierRequest`, then pass it to `sendCourierMail`.
+ */
+export interface CourierRequest {
+    /** Email header title */
+    title: string;
+    /** Email subject line */
+    subject: string;
+    /** Body content of the email */
+    message: string;
+    /** Recipient email address */
+    receiver: string;
+    /** Reply-to email address */
+    reply_mail: string;
+    /** Optional action button included in the email */
+    link: CourierLink | null;
+    /** Transaction/signature identifier — set automatically when the request is signed */
+    trx?: string;
+}
+
+/**
+ * Request payload for sending an exception/error notification email.
+ * Build this object using `createCourierExceptionRequest`, then pass it to `sendExceptionMail`.
+ */
+export interface CourierExceptionRequest {
+    /** Error name or type */
+    error: string;
+    /** Detailed error message */
+    detail: string;
+    /** Application context where the error occurred (e.g. service name, endpoint) */
+    context: string;
+    /** Transaction/signature identifier — set automatically when the request is signed */
+    trx?: string;
+}
+
+/**
+ * Request payload for customer-related emails (register, password update, etc.).
+ * Build this object using `createCustomerMailerRequest`, then pass it to the
+ * corresponding `sendMail*` customer function.
+ */
+export interface CustomerMailerRequest {
+    /** Username or email of the customer */
+    user: string;
+    /** Customer password (used in registration emails) */
+    password: string;
+    /** Product name shown in the email */
+    product: string;
+    /** Verification or action token included in the email */
+    token: string;
+    /** Reply-to email address */
+    reply_mail: string;
+    /** Transaction/signature identifier — set automatically when the request is signed */
+    trx?: string;
+}
+
+/**
+ * Request payload for payment notification emails.
+ * Build this object using `createPaymentsMailerRequest`, then pass it to `sendMailPayment`.
+ */
+export interface PaymentsMailerRequest {
+    /** Transaction ID associated with the payment */
+    trxId: string;
+    /** Product licence or identifier related to the payment */
+    licence: string;
+    /** Transaction/signature identifier — set automatically when the request is signed */
+    trx?: string;
+}
+
+// ---------------------------------------------------------------------------
+// COURIER
+// ---------------------------------------------------------------------------
+
+/**
+ * Creates a `CourierRequest` object ready to be sent via `sendCourierMail`.
+ *
+ * @param title - Header title displayed in the email template.
+ * @param subject - Subject line of the email.
+ * @param message - Main body/content of the email.
+ * @param receiver - Recipient email address.
+ * @param reply_mail - Reply-to email address.
+ * @param btn_label - Label for the optional call-to-action button. Pass `null` to omit the button.
+ * @param btn_link - URL for the optional call-to-action button. Pass `null` to omit the button.
+ * @returns A `CourierRequest` instance. Sign it (add a `trx` field) before calling `sendCourierMail`.
+ *
+ * @example
+ * const request = createCourierRequest(
+ *   'Nuevo mensaje',
+ *   'Tienes un mensaje pendiente',
+ *   'Hola, revisa tu bandeja.',
+ *   'cliente@ejemplo.com',
+ *   'soporte@miapp.com',
+ *   'Ver mensaje',
+ *   'https://miapp.com/mensajes'
+ * );
+ */
+export function createCourierRequest(
+    title: string,
+    subject: string,
+    message: string,
+    receiver: string,
+    reply_mail: string,
+    btn_label: string | null,
+    btn_link: string | null
+): CourierRequest;
+
+/**
+ * Creates a `CourierExceptionRequest` object ready to be sent via `sendExceptionMail`.
+ *
+ * @param error - Error name or type (e.g. `'NullPointerException'`, `'HTTP 500'`).
+ * @param detail - Detailed error message or stack trace excerpt.
+ * @param context - Context where the error occurred (e.g. service name, endpoint, module).
+ * @returns A `CourierExceptionRequest` instance. Sign it (add a `trx` field) before calling `sendExceptionMail`.
+ *
+ * @example
+ * const request = createCourierExceptionRequest(
+ *   'UnhandledError',
+ *   'Cannot read property of undefined at processPayment',
+ *   'PaymentService.processPayment'
+ * );
+ */
+export function createCourierExceptionRequest(
+    error: string,
+    detail: string,
+    context: string
+): CourierExceptionRequest;
+
+/**
+ * Sends a general-purpose courier email via the SDX Mailer API.
+ *
+ * The `tokenRQ` must be a **signed** `CourierRequest` (i.e. it must have a `trx` field set).
+ * Throws a `WebServiceException` if the request is not signed or if the API call fails.
+ *
+ * @param basicAuth - Authorization header value (e.g. `'Basic dXNlcjpwYXNz'`). Pass `null` to send without auth.
+ * @param endpoint - Base URL of the SDX Mailer API (e.g. `'https://mailer.miapp.com'`).
+ * @param tokenRQ - Signed `CourierRequest` to send.
+ * @param productId - Numeric identifier of the product making the request.
+ * @param isBasic - When `true`, sends to the `/basic` variant of the courier endpoint.
+ * @returns A promise that resolves with the API response data.
+ *
+ * @example
+ * const response = await sendCourierMail('Basic dXNlcjpwYXNz', 'https://mailer.miapp.com', signedRequest, 1, false);
+ */
+export function sendCourierMail(
+    basicAuth: string | null,
+    endpoint: string,
+    tokenRQ: CourierRequest,
+    productId: number,
+    isBasic: boolean
+): Promise<any>;
+
+/**
+ * Sends an exception/error notification email via the SDX Mailer API.
+ *
+ * The `tokenRQ` must be a **signed** `CourierExceptionRequest` (i.e. it must have a `trx` field set).
+ * Throws a `WebServiceException` if the request is not signed or if the API call fails.
+ *
+ * @param basicAuth - Authorization header value (e.g. `'Basic dXNlcjpwYXNz'`). Pass `null` to send without auth.
+ * @param endpoint - Base URL of the SDX Mailer API (e.g. `'https://mailer.miapp.com'`).
+ * @param tokenRQ - Signed `CourierExceptionRequest` to send.
+ * @param productId - Numeric identifier of the product making the request.
+ * @returns A promise that resolves with the API response data.
+ *
+ * @example
+ * const response = await sendExceptionMail('Basic dXNlcjpwYXNz', 'https://mailer.miapp.com', signedRequest, 1);
+ */
+export function sendExceptionMail(
+    basicAuth: string | null,
+    endpoint: string,
+    tokenRQ: CourierExceptionRequest,
+    productId: number
+): Promise<any>;
+
+// ---------------------------------------------------------------------------
+// CUSTOMER
+// ---------------------------------------------------------------------------
+
+/**
+ * Creates a `CustomerMailerRequest` object used for all customer email flows
+ * (register, password update, etc.).
+ *
+ * @param user - Username or email address of the customer.
+ * @param password - Customer's password (included in registration emails).
+ * @param product - Product name displayed in the email template.
+ * @param token - Verification or action token to embed in the email (e.g. for password reset links).
+ * @param reply_mail - Reply-to email address shown in the email.
+ * @returns A `CustomerMailerRequest` instance. Sign it (add a `trx` field) before calling any `sendMail*` function.
+ *
+ * @example
+ * const request = createCustomerMailerRequest(
+ *   'usuario@ejemplo.com',
+ *   'MiP@ss123',
+ *   'MiProducto',
+ *   'abc123token',
+ *   'soporte@miapp.com'
+ * );
+ */
+export function createCustomerMailerRequest(
+    user: string,
+    password: string,
+    product: string,
+    token: string,
+    reply_mail: string
+): CustomerMailerRequest;
+
+/**
+ * Sends a "update your password" notification email to the customer.
+ *
+ * The `tokenRQ` must be a **signed** `CustomerMailerRequest` (i.e. it must have a `trx` field set).
+ * Throws a `WebServiceException` if the request is not signed or if the API call fails.
+ *
+ * @param basicAuth - Authorization header value (e.g. `'Basic dXNlcjpwYXNz'`). Pass `null` to send without auth.
+ * @param endpoint - Base URL of the SDX Mailer API (e.g. `'https://mailer.miapp.com'`).
+ * @param tokenRQ - Signed `CustomerMailerRequest` to send.
+ * @returns A promise that resolves with the API response data.
+ */
+export function sendMailUpdatePassword(
+    basicAuth: string | null,
+    endpoint: string,
+    tokenRQ: CustomerMailerRequest
+): Promise<any>;
+
+/**
+ * Sends a "password updated successfully" confirmation email to the customer.
+ *
+ * The `tokenRQ` must be a **signed** `CustomerMailerRequest` (i.e. it must have a `trx` field set).
+ * Throws a `WebServiceException` if the request is not signed or if the API call fails.
+ *
+ * @param basicAuth - Authorization header value (e.g. `'Basic dXNlcjpwYXNz'`). Pass `null` to send without auth.
+ * @param endpoint - Base URL of the SDX Mailer API (e.g. `'https://mailer.miapp.com'`).
+ * @param tokenRQ - Signed `CustomerMailerRequest` to send.
+ * @returns A promise that resolves with the API response data.
+ */
+export function sendMailSuccessUpdatedPassword(
+    basicAuth: string | null,
+    endpoint: string,
+    tokenRQ: CustomerMailerRequest
+): Promise<any>;
+
+/**
+ * Sends a customer registration welcome email.
+ *
+ * The `tokenRQ` must be a **signed** `CustomerMailerRequest` (i.e. it must have a `trx` field set).
+ * Throws a `WebServiceException` if the request is not signed or if the API call fails.
+ *
+ * @param basicAuth - Authorization header value (e.g. `'Basic dXNlcjpwYXNz'`). Pass `null` to send without auth.
+ * @param endpoint - Base URL of the SDX Mailer API (e.g. `'https://mailer.miapp.com'`).
+ * @param tokenRQ - Signed `CustomerMailerRequest` to send.
+ * @returns A promise that resolves with the API response data.
+ */
+export function sendMailRegister(
+    basicAuth: string | null,
+    endpoint: string,
+    tokenRQ: CustomerMailerRequest
+): Promise<any>;
+
+/**
+ * Sends a customer registration email triggered by an owner/admin on behalf of the customer.
+ *
+ * The `tokenRQ` must be a **signed** `CustomerMailerRequest` (i.e. it must have a `trx` field set).
+ * Throws a `WebServiceException` if the request is not signed or if the API call fails.
+ *
+ * @param basicAuth - Authorization header value (e.g. `'Basic dXNlcjpwYXNz'`). Pass `null` to send without auth.
+ * @param endpoint - Base URL of the SDX Mailer API (e.g. `'https://mailer.miapp.com'`).
+ * @param tokenRQ - Signed `CustomerMailerRequest` to send.
+ * @returns A promise that resolves with the API response data.
+ */
+export function sendMailRegisterByOwner(
+    basicAuth: string | null,
+    endpoint: string,
+    tokenRQ: CustomerMailerRequest
+): Promise<any>;
+
+// ---------------------------------------------------------------------------
+// CUSTOM MAIL
+// ---------------------------------------------------------------------------
+
+/**
+ * Request payload for sending a fully custom HTML email.
+ * Build this object using `createCustomMailRequest`, then pass it to `sendCustomMail`.
+ */
+export interface CustomMailRequest {
+    /** Subject line of the email */
+    subject: string;
+    /** Recipient email address */
+    email: string;
+    /** List of CC email addresses */
+    cc: string[];
+    /** Full HTML content of the email body */
+    content: string;
+}
+
+/**
+ * Creates a `CustomMailRequest` object ready to be sent via `sendCustomMail`.
+ *
+ * @param subject - Subject line of the email.
+ * @param email - Recipient email address.
+ * @param content - Full HTML content of the email body.
+ * @param cc - Optional list of CC email addresses.
+ * @returns A `CustomMailRequest` instance.
+ *
+ * @example
+ * const request = createCustomMailRequest(
+ *   'Welcome to our platform',
+ *   'user@example.com',
+ *   '<h1>Hello!</h1><p>Your account is ready.</p>',
+ *   ['manager@example.com']
+ * );
+ */
+export function createCustomMailRequest(
+    subject: string,
+    email: string,
+    content: string,
+    cc?: string[]
+): CustomMailRequest;
+
+/**
+ * Sends a fully custom HTML email via the SDX Mailer API.
+ * Authenticated with an API key sent as the `x-api-key` header.
+ * The key must follow the format `sdx_<prefix>.<secret>` and have at least one
+ * permission with `can_execute: true`.
+ *
+ * @param apiKey - API key in the format `sdx_<prefix>.<secret>` (e.g. `'sdx_abc123xyz.mysecret'`).
+ * @param endpoint - Base URL of the SDX Mailer API (e.g. `'https://mailer.miapp.com'`).
+ * @param request - `CustomMailRequest` payload to send.
+ * @returns A promise that resolves with the API response data.
+ *
+ * @example
+ * const response = await sendCustomMail(
+ *   'sdx_abc123xyz.mysecret',
+ *   'https://mailer.miapp.com',
+ *   request
+ * );
+ */
+export function sendCustomMail(
+    apiKey: string,
+    endpoint: string,
+    request: CustomMailRequest
+): Promise<any>;
+
+// ---------------------------------------------------------------------------
+// PAYMENTS
+// ---------------------------------------------------------------------------
+
+/**
+ * Creates a `PaymentsMailerRequest` object ready to be sent via `sendMailPayment`.
+ *
+ * @param trxId - Transaction ID associated with the payment (e.g. order ID, payment reference).
+ * @param product - Product name or licence identifier related to the payment.
+ * @returns A `PaymentsMailerRequest` instance. Sign it (add a `trx` field) before calling `sendMailPayment`.
+ *
+ * @example
+ * const request = createPaymentsMailerRequest('TRX-00123', 'PlanPro');
+ */
+export function createPaymentsMailerRequest(
+    trxId: string,
+    product: string
+): PaymentsMailerRequest;
+
+/**
+ * Sends a payment confirmation email via the SDX Mailer API.
+ *
+ * The `tokenRQ` must be a **signed** `PaymentsMailerRequest` (i.e. it must have a `trx` field set).
+ * Throws a `WebServiceException` if the request is not signed or if the API call fails.
+ *
+ * @param basicAuth - Authorization header value (e.g. `'Basic dXNlcjpwYXNz'`). Pass `null` to send without auth.
+ * @param endpoint - Base URL of the SDX Mailer API (e.g. `'https://mailer.miapp.com'`).
+ * @param tokenRQ - Signed `PaymentsMailerRequest` to send.
+ * @returns A promise that resolves with the API response data.
+ *
+ * @example
+ * const response = await sendMailPayment('Basic dXNlcjpwYXNz', 'https://mailer.miapp.com', signedRequest);
+ */
+export function sendMailPayment(
+    basicAuth: string | null,
+    endpoint: string,
+    tokenRQ: PaymentsMailerRequest
+): Promise<any>;

package/index.js

@@ -1,140 +1,174 @@
 const CourierMail = require('./src/CourierMail');
 const CustomerMail = require('./src/CustomerMail')
 const PaymentsMail = require('./src/PaymentsMail')
+const CustomMail = require('./src/CustomMail')
 
 const courierMailInstance = new CourierMail();
 const customerMailInstance = new CustomerMail();
 const paymentsMailInstance = new PaymentsMail();
+const customMailInstance = new CustomMail();
 
 /**
- * Method for CourierRequest creation
- * @param {*} title 
- * @param {*} subject 
- * @param {*} message 
- * @param {*} receiver 
- * @param {*} reply_mail 
- * @param {*} btn_label 
- * @param {*} btn_link 
- * @returns 
+ * Creates a `CourierRequest` object ready to be sent via `sendCourierMail`.
+ * @param {string} title - Header title displayed in the email template.
+ * @param {string} subject - Subject line of the email.
+ * @param {string} message - Main body/content of the email.
+ * @param {string} receiver - Recipient email address.
+ * @param {string} reply_mail - Reply-to email address.
+ * @param {string|null} btn_label - Label for the optional call-to-action button. Pass `null` to omit it.
+ * @param {string|null} btn_link - URL for the optional call-to-action button. Pass `null` to omit it.
+ * @returns {import('./src/entities/CourierRequest')} A CourierRequest instance. Sign it before calling `sendCourierMail`.
  */
 function createCourierRequest(title, subject, message, receiver, reply_mail, btn_label, btn_link) {
     return courierMailInstance.createCourierRequest(title, subject, message, receiver, reply_mail, btn_label, btn_link)
 }
 
 /**
- * Method for CourierExceptionRequest creation
- * @param {*} error 
- * @param {*} detail 
- * @param {*} context 
- * @returns 
+ * Creates a `CourierExceptionRequest` object ready to be sent via `sendExceptionMail`.
+ * @param {string} error - Error name or type (e.g. `'HTTP 500'`, `'UnhandledError'`).
+ * @param {string} detail - Detailed error message or stack trace excerpt.
+ * @param {string} context - Context where the error occurred (e.g. service name, endpoint).
+ * @returns {import('./src/entities/CourierExceptionRequest')} A CourierExceptionRequest instance. Sign it before calling `sendExceptionMail`.
  */
 function createCourierExceptionRequest(error, detail, context) {
     return courierMailInstance.createCourierExceptionRequest(error, detail, context)
 }
 
 /**
- * Method for send CourierRequest
- * @param {*} basicAuth 
- * @param {*} endpoint 
- * @param {*} tokenRQ 
- * @param {*} productId 
- * @param {*} isBasic 
- * @returns 
+ * Sends a general-purpose courier email via the SDX Mailer API.
+ * The `tokenRQ` must be signed (have a `trx` field). Throws if not signed or if the API fails.
+ * @param {string|null} basicAuth - Authorization header value (e.g. `'Basic dXNlcjpwYXNz'`). Pass `null` to send without auth.
+ * @param {string} endpoint - Base URL of the SDX Mailer API (e.g. `'https://mailer.miapp.com'`).
+ * @param {import('./src/entities/CourierRequest')} tokenRQ - Signed CourierRequest to send.
+ * @param {number} productId - Numeric identifier of the product making the request.
+ * @param {boolean} isBasic - When `true`, sends to the `/basic` variant of the courier endpoint.
+ * @returns {Promise<any>} Resolves with the API response data.
  */
 async function sendCourierMail(basicAuth, endpoint, tokenRQ, productId, isBasic) {
     return courierMailInstance.sendCourierMail(basicAuth, endpoint, tokenRQ, productId, isBasic)
 }
 
 /**
- * Method for send CourierExceptionRequest
- * @param {*} basicAuth 
- * @param {*} endpoint 
- * @param {*} tokenRQ 
- * @param {*} productId 
- * @returns 
+ * Sends an exception/error notification email via the SDX Mailer API.
+ * The `tokenRQ` must be signed (have a `trx` field). Throws if not signed or if the API fails.
+ * @param {string|null} basicAuth - Authorization header value (e.g. `'Basic dXNlcjpwYXNz'`). Pass `null` to send without auth.
+ * @param {string} endpoint - Base URL of the SDX Mailer API (e.g. `'https://mailer.miapp.com'`).
+ * @param {import('./src/entities/CourierExceptionRequest')} tokenRQ - Signed CourierExceptionRequest to send.
+ * @param {number} productId - Numeric identifier of the product making the request.
+ * @returns {Promise<any>} Resolves with the API response data.
  */
 async function sendExceptionMail(basicAuth, endpoint, tokenRQ, productId) {
     return courierMailInstance.sendExceptionMail(basicAuth, endpoint, tokenRQ, productId)
 }
 
 /**
- * Method for CustomerMailerRequest creation
- * @param {*} user 
- * @param {*} password 
- * @param {*} product 
- * @param {*} token 
- * @param {*} reply_mail 
- * @returns 
+ * Creates a `CustomerMailerRequest` object used for all customer email flows (register, password update, etc.).
+ * @param {string} user - Username or email address of the customer.
+ * @param {string} password - Customer's password (included in registration emails).
+ * @param {string} product - Product name displayed in the email template.
+ * @param {string} token - Verification or action token to embed in the email (e.g. for password reset links).
+ * @param {string} reply_mail - Reply-to email address shown in the email.
+ * @returns {import('./src/entities/CustomerMailerRequest')} A CustomerMailerRequest instance. Sign it before calling any `sendMail*` function.
  */
 function createCustomerMailerRequest(user, password, product, token, reply_mail) {
     return customerMailInstance.createCustomerMailerRequest(user, password, product, token, reply_mail)
 }
 
 /**
- * Send Customer update password Mail
- * @param {*} basicAuth 
- * @param {*} endpoint 
- * @param {*} tokenRQ 
- * @returns 
+ * Sends a "update your password" notification email to the customer.
+ * The `tokenRQ` must be signed (have a `trx` field). Throws if not signed or if the API fails.
+ * @param {string|null} basicAuth - Authorization header value (e.g. `'Basic dXNlcjpwYXNz'`). Pass `null` to send without auth.
+ * @param {string} endpoint - Base URL of the SDX Mailer API (e.g. `'https://mailer.miapp.com'`).
+ * @param {import('./src/entities/CustomerMailerRequest')} tokenRQ - Signed CustomerMailerRequest to send.
+ * @returns {Promise<any>} Resolves with the API response data.
  */
 async function sendMailUpdatePassword(basicAuth, endpoint, tokenRQ) {
     return customerMailInstance.sendMailUpdatePassword(basicAuth, endpoint, tokenRQ)
 }
 
 /**
- * Send Customer success update password Mail
- * @param {*} basicAuth 
- * @param {*} endpoint 
- * @param {*} tokenRQ 
- * @returns 
+ * Sends a "password updated successfully" confirmation email to the customer.
+ * The `tokenRQ` must be signed (have a `trx` field). Throws if not signed or if the API fails.
+ * @param {string|null} basicAuth - Authorization header value (e.g. `'Basic dXNlcjpwYXNz'`). Pass `null` to send without auth.
+ * @param {string} endpoint - Base URL of the SDX Mailer API (e.g. `'https://mailer.miapp.com'`).
+ * @param {import('./src/entities/CustomerMailerRequest')} tokenRQ - Signed CustomerMailerRequest to send.
+ * @returns {Promise<any>} Resolves with the API response data.
  */
 async function sendMailSuccessUpdatedPassword(basicAuth, endpoint, tokenRQ) {
     return customerMailInstance.sendMailSuccessUpdatedPassword(basicAuth, endpoint, tokenRQ)
 }
 
 /**
- * Send Customer register Mail
- * @param {*} basicAuth 
- * @param {*} endpoint 
- * @param {*} tokenRQ 
- * @returns 
+ * Sends a customer registration welcome email.
+ * The `tokenRQ` must be signed (have a `trx` field). Throws if not signed or if the API fails.
+ * @param {string|null} basicAuth - Authorization header value (e.g. `'Basic dXNlcjpwYXNz'`). Pass `null` to send without auth.
+ * @param {string} endpoint - Base URL of the SDX Mailer API (e.g. `'https://mailer.miapp.com'`).
+ * @param {import('./src/entities/CustomerMailerRequest')} tokenRQ - Signed CustomerMailerRequest to send.
+ * @returns {Promise<any>} Resolves with the API response data.
  */
 async function sendMailRegister(basicAuth, endpoint, tokenRQ) {
     return customerMailInstance.sendMailRegister(basicAuth, endpoint, tokenRQ)
 }
 
 /**
- * Send Customer register by owner Mail
- * @param {*} basicAuth 
- * @param {*} endpoint 
- * @param {*} tokenRQ 
- * @returns 
+ * Sends a customer registration email triggered by an owner/admin on behalf of the customer.
+ * The `tokenRQ` must be signed (have a `trx` field). Throws if not signed or if the API fails.
+ * @param {string|null} basicAuth - Authorization header value (e.g. `'Basic dXNlcjpwYXNz'`). Pass `null` to send without auth.
+ * @param {string} endpoint - Base URL of the SDX Mailer API (e.g. `'https://mailer.miapp.com'`).
+ * @param {import('./src/entities/CustomerMailerRequest')} tokenRQ - Signed CustomerMailerRequest to send.
+ * @returns {Promise<any>} Resolves with the API response data.
  */
 async function sendMailRegisterByOwner(basicAuth, endpoint, tokenRQ) {
     return customerMailInstance.sendMailRegisterByOwner(basicAuth, endpoint, tokenRQ)
 }
 
 /**
- * Method for PaymentsMailerRequest creation
- * @param {*} trxId 
- * @param {*} product
- * @returns 
+ * Creates a `PaymentsMailerRequest` object ready to be sent via `sendMailPayment`.
+ * @param {string} trxId - Transaction ID associated with the payment (e.g. order ID, payment reference).
+ * @param {string} product - Product name or licence identifier related to the payment.
+ * @returns {import('./src/entities/PaymentsMailerRequest')} A PaymentsMailerRequest instance. Sign it before calling `sendMailPayment`.
  */
 function createPaymentsMailerRequest(trxId, product) {
     return paymentsMailInstance.createPaymentsMailerRequest(trxId, product)
 }
 
 /**
- * Send payment Mail
- * @param {*} basicAuth 
- * @param {*} endpoint 
- * @param {*} tokenRQ 
- * @returns 
+ * Sends a payment confirmation email via the SDX Mailer API.
+ * The `tokenRQ` must be signed (have a `trx` field). Throws if not signed or if the API fails.
+ * @param {string|null} basicAuth - Authorization header value (e.g. `'Basic dXNlcjpwYXNz'`). Pass `null` to send without auth.
+ * @param {string} endpoint - Base URL of the SDX Mailer API (e.g. `'https://mailer.miapp.com'`).
+ * @param {import('./src/entities/PaymentsMailerRequest')} tokenRQ - Signed PaymentsMailerRequest to send.
+ * @returns {Promise<any>} Resolves with the API response data.
  */
 async function sendMailPayment(basicAuth, endpoint, tokenRQ) {
     return paymentsMailInstance.sendMailPayment(basicAuth, endpoint, tokenRQ)
 }
 
+/**
+ * Creates a `CustomMailRequest` object ready to be sent via `sendCustomMail`.
+ * @param {string} subject - Subject line of the email.
+ * @param {string} email - Recipient email address.
+ * @param {string} content - Full HTML content of the email body.
+ * @param {string[]} [cc] - Optional list of CC email addresses.
+ * @returns {import('./src/entities/CustomMailRequest')} A CustomMailRequest instance.
+ */
+function createCustomMailRequest(subject, email, content, cc) {
+    return customMailInstance.createCustomMailRequest(subject, email, content, cc)
+}
+
+/**
+ * Sends a fully custom HTML email via the SDX Mailer API.
+ * Authenticated with an API key (`x-api-key` header) in the format `sdx_<prefix>.<secret>`.
+ * The API key must have at least one permission with `can_execute: true`.
+ * @param {string} apiKey - API key in the format `sdx_<prefix>.<secret>`.
+ * @param {string} endpoint - Base URL of the SDX Mailer API (e.g. `'https://mailer.miapp.com'`).
+ * @param {import('./src/entities/CustomMailRequest')} request - CustomMailRequest to send.
+ * @returns {Promise<any>} Resolves with the API response data.
+ */
+async function sendCustomMail(apiKey, endpoint, request) {
+    return customMailInstance.sendCustomMail(apiKey, endpoint, request)
+}
+
 module.exports = {
     sendCourierMail,                        // COURIER
     sendExceptionMail,                      // COURIER
@@ -146,5 +180,7 @@ module.exports = {
     sendMailRegisterByOwner,                // CUSTOMER
     createCustomerMailerRequest,            // CUSTOMER
     sendMailPayment,                        // PAYMENT
-    createPaymentsMailerRequest             // PAYMENT
+    createPaymentsMailerRequest,            // PAYMENT
+    createCustomMailRequest,                // CUSTOM
+    sendCustomMail                          // CUSTOM
 };

package/package.json

@@ -1,8 +1,14 @@
 {
   "name": "sdx-mailer-sdk",
-  "version": "1.0.19",
+  "version": "1.0.21",
   "description": "A api rest sdx-mailer-sender sdk",
   "main": "index.js",
+  "types": "index.d.ts",
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "src/"
+  ],
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"
   },

package/src/CustomMail.js

@@ -0,0 +1,40 @@
+const CustomMailRequest = require('./entities/CustomMailRequest');
+const WebServiceException = require('./entities/WebServiceException');
+const CourierService = require('./services/CourierService');
+const Commons = require('./utils/Commons');
+
+class CustomMail {
+
+    static BASE_PATH = '/v1/courier/custom-mail'
+
+    constructor() {
+        this.service = new CourierService();
+    }
+
+    createCustomMailRequest(subject, email, content, cc) {
+        let request = new CustomMailRequest();
+        request.subject = subject;
+        request.email = email;
+        request.content = content;
+        request.cc = Array.isArray(cc) ? cc : [];
+        return request;
+    }
+
+    /**
+     * Send a fully custom HTML email via the SDX Mailer API.
+     * Authenticated with an API key (x-api-key header).
+     * @param {string} apiKey
+     * @param {string} endpoint
+     * @param {CustomMailRequest} request
+     * @returns
+     */
+    async sendCustomMail(apiKey, endpoint, request) {
+        if (!Commons.validField(apiKey)) {
+            throw WebServiceException.BAD_REQUEST('An API key is required to send a custom mail');
+        }
+        const url = endpoint + CustomMail.BASE_PATH;
+        return await this.service.postMailWithApiKey(apiKey, request, url, 'sendCustomMail');
+    }
+}
+
+module.exports = CustomMail;

package/src/PaymentsMail.js

@@ -13,7 +13,7 @@ class PaymentsMail {
 
     createPaymentsMailerRequest(trxId, licence) {
         let request = new PaymentsMailerRequest();
-        request.user = trxId;
+        request.trxId = trxId;
         request.licence = licence;
         return request;
     }

package/src/entities/CustomMailRequest.js

@@ -0,0 +1,10 @@
+class CustomMailRequest {
+    constructor() {
+        this.subject = '';
+        this.email = '';
+        this.cc = [];
+        this.content = '';
+    }
+}
+
+module.exports = CustomMailRequest;

package/src/services/CourierService.js

@@ -11,6 +11,15 @@ class CourierService {
         }
     }
 
+    async postMailWithApiKey(apiKey, body, url, methodName) {
+        try {
+            const res = await axios.post(url, body, { headers: { 'x-api-key': apiKey } });
+            return res.data;
+        } catch (err) {
+            throw Commons.buildWebServiceException(err, 'POST', methodName);
+        }
+    }
+
     buildOptions(basicAuth, productId) {
         if (basicAuth !== null) {
             return {