@easybits.cloud/mailmask 0.8.0 → 0.9.1

package/README.md

@@ -156,6 +156,15 @@ const job = await mm.batch("formmy-user-42", {
 const st = await mm.batchStatus("formmy-user-42", job.batchId);
 // st.sent / failed / skippedSuppressed, then (for up to 7 days) delivered / bounced / complained / unsubscribed
 
+// Opens and clicks (opt-in per send/batch): `track: true` adds SES's open pixel and rewrites the html
+// links. Without it nothing is added. Unique counts + rates + top links come back in batchStatus, and
+// `email.opened` / `email.clicked` fire once per message (the first time). Opens are inflated by Apple
+// Mail Privacy Protection: decide by clicks.
+const tracked = await mm.batch("formmy-user-42", { from: "hola@laespiga.mx", subject: "Oct", html: "<a href=\"https://laespiga.mx/menu?utm_source=mail\">Menú</a>", recipients: ["ana@example.com"], track: true });
+const ts = await mm.batchStatus("formmy-user-42", tracked.batchId);
+// ts.opened / clicked (unique), ts.openRate / clickRate (0–1 over delivered, or sent while delivered is 0),
+// ts.topLinks: [{ url: "https://laespiga.mx/menu", clicks, uniqueClicks }] (utm_*, fbclid, gclid stripped)
+
 // Test mode: validates everything (signature, domain, suppression, quota) without sending or billing
 await mm.send("formmy-user-42", { from: "hola@laespiga.mx", to: "x@example.com", subject: "s", text: "t" }, { test: true });
 
@@ -208,6 +217,9 @@ export async function action({ request }: { request: Request }) {
     case "tenant.paused":
       // notify the customer
       break;
+    case "email.clicked":
+      // event.data.url, event.data.recipient, event.data.batchId, event.data.tags (first click only)
+      break;
   }
   return new Response("ok");
 }

package/dist/index.cjs

@@ -20,6 +20,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  AUTO_TOPUP_SUGGESTIONS: () => AUTO_TOPUP_SUGGESTIONS,
   AuthError: () => AuthError,
   BALANCE_LOW_FRACTION: () => BALANCE_LOW_FRACTION,
   BALANCE_MOVEMENT_KINDS: () => BALANCE_MOVEMENT_KINDS,
@@ -44,8 +45,10 @@ __export(index_exports, {
   NotFoundError: () => NotFoundError,
   PARTNER_ADMIN_ROUTES: () => PARTNER_ADMIN_ROUTES,
   PARTNER_API_PREFIX: () => PARTNER_API_PREFIX,
+  PARTNER_CURRENCIES: () => PARTNER_CURRENCIES,
   PARTNER_ERROR_STATUS: () => PARTNER_ERROR_STATUS,
   PARTNER_HEADERS: () => PARTNER_HEADERS,
+  PARTNER_PRICES: () => PARTNER_PRICES,
   PARTNER_PRICE_PER_EMAIL_CENTS: () => PARTNER_PRICE_PER_EMAIL_CENTS,
   PARTNER_ROUTES: () => PARTNER_ROUTES,
   PARTNER_SIGNATURE_TOLERANCE_S: () => PARTNER_SIGNATURE_TOLERANCE_S,
@@ -74,6 +77,7 @@ __export(index_exports, {
   WEBHOOK_TOLERANCE_MS: () => WEBHOOK_TOLERANCE_MS,
   createWebhookHandler: () => createWebhookHandler,
   estimateSendDays: () => estimateSendDays,
+  formatMoney: () => formatMoney,
   isValidExternalId: () => isValidExternalId,
   isValidFallbackLabel: () => isValidFallbackLabel,
   partnerSignatureBase: () => partnerSignatureBase,
@@ -755,7 +759,7 @@ var MAX_BATCH_RECIPIENTS = 1e4;
 var MAX_TAGS = 10;
 var TAG_RE = /^[A-Za-z0-9_-]{1,64}$/;
 var TENANT_DAILY_LIMIT_START = 2e3;
-var TENANT_DAILY_LIMIT_MAX = 5e4;
+var TENANT_DAILY_LIMIT_MAX = 2e4;
 var TENANT_WARMUP_STEP_DAYS = 7;
 function warmupLimit(step) {
   return Math.min(TENANT_DAILY_LIMIT_MAX, TENANT_DAILY_LIMIT_START * 2 ** Math.max(0, step));
@@ -843,18 +847,32 @@ function personalizePartnerMessage(input) {
     ...text !== void 0 ? { text: renderTemplate(text, vars) } : {}
   };
 }
-var PARTNER_PRICE_PER_EMAIL_CENTS = 6;
-var PARTNER_TENANT_MONTH_CENTS = 4900;
-var PARTNER_WELCOME_CENTS = 5e4;
-var PARTNER_TOPUP_MIN_CENTS = 5e4;
-var PARTNER_TOPUP_MAX_CENTS = 1e7;
+var PARTNER_CURRENCIES = ["MXN", "USD"];
+var PARTNER_PRICES = {
+  MXN: { perEmailCents: 6, tenantMonthCents: 4900, welcomeCents: 5e4, topupMinCents: 5e4, topupMaxCents: 1e7 },
+  USD: { perEmailCents: 0.35, tenantMonthCents: 290, welcomeCents: 2900, topupMinCents: 2900, topupMaxCents: 55e4 }
+};
+var PARTNER_PRICE_PER_EMAIL_CENTS = PARTNER_PRICES.MXN.perEmailCents;
+var PARTNER_TENANT_MONTH_CENTS = PARTNER_PRICES.MXN.tenantMonthCents;
+var PARTNER_WELCOME_CENTS = PARTNER_PRICES.MXN.welcomeCents;
+var PARTNER_TOPUP_MIN_CENTS = PARTNER_PRICES.MXN.topupMinCents;
+var PARTNER_TOPUP_MAX_CENTS = PARTNER_PRICES.MXN.topupMaxCents;
+function formatMoney(cents, currency) {
+  const v = Math.abs(cents) / 100;
+  const decimals = v !== 0 && v < 0.01 ? 4 : 2;
+  const n = v.toLocaleString("en-US", { minimumFractionDigits: decimals, maximumFractionDigits: decimals });
+  return `${cents < 0 ? "\u2212" : ""}$${n} ${currency}`;
+}
 var BALANCE_LOW_FRACTION = 0.2;
 var BALANCE_MOVEMENT_KINDS = ["topup", "send", "tenant_fee", "refund", "adjust"];
+var AUTO_TOPUP_SUGGESTIONS = { MXN: [500, 1e3, 2500], USD: [29, 59, 149] };
 var PARTNER_WEBHOOK_EVENTS = [
   "email.sent",
   "email.delivered",
   "email.bounced",
   "email.complained",
+  "email.opened",
+  "email.clicked",
   "email.received",
   "contact.unsubscribed",
   "tenant.paused",
@@ -896,6 +914,8 @@ var PARTNER_ROUTES = {
   balance: { method: "GET", path: "/balance" },
   balanceMovements: { method: "GET", path: "/balance/movements" },
   topup: { method: "POST", path: "/topup" },
+  getAutoTopup: { method: "GET", path: "/auto-topup" },
+  setAutoTopup: { method: "PUT", path: "/auto-topup" },
   getWebhook: { method: "GET", path: "/webhook" },
   setWebhook: { method: "PUT", path: "/webhook" },
   testWebhook: { method: "POST", path: "/webhook/test" },
@@ -917,6 +937,10 @@ var PARTNER_ADMIN_ROUTES = {
   adjustBalance: { method: "POST", path: "/api/partners/:partnerId/balance/adjust" },
   /** Recarga con MercadoPago desde la sesión del dueño (misma respuesta que `POST /topup`). */
   topup: { method: "POST", path: "/api/partners/:partnerId/topup" },
+  getAutoTopup: { method: "GET", path: "/api/partners/:partnerId/auto-topup" },
+  setAutoTopup: { method: "PUT", path: "/api/partners/:partnerId/auto-topup" },
+  /** Sólo MailMask: moneda del saldo, mientras no haya más movimientos que la bienvenida. */
+  setCurrency: { method: "PUT", path: "/api/partners/:partnerId/currency" },
   /** Sólo MailMask: fija (o quita, con `null`) el límite diario de un tenant. Devuelve el `Tenant`. */
   setTenantDailyLimit: { method: "PUT", path: "/api/partners/:partnerId/tenants/:externalId/daily-limit" },
   listCredentials: { method: "GET", path: "/api/partners/:partnerId/credentials" },
@@ -1058,6 +1082,10 @@ var InsufficientBalanceError = class extends PartnerApiError {
   get requiredCents() {
     return this.body.requiredCents;
   }
+  /** Moneda de los dos montos de arriba. */
+  get currency() {
+    return this.body.currency;
+  }
 };
 var NetworkError = class extends PartnerApiError {
   constructor(message, cause) {
@@ -1280,7 +1308,10 @@ var MailMaskPartner = class {
     );
     return { ...data, idempotencyKey, replayed: meta.idempotentReplayed };
   }
-  /** Estado de un lote (`batchId` del resultado de `batch`): envíos y, después, entregas, rebotes, quejas y bajas. */
+  /**
+   * Estado de un lote (`batchId` del resultado de `batch`): envíos y, después, entregas, rebotes, quejas
+   * y bajas; con `track: true`, también aperturas, clics, tasas y `topLinks`.
+   */
   async batchStatus(externalId, batchId) {
     return (await this.request("GET", routePath(PARTNER_ROUTES.getBatch.path, { externalId, batchId }))).data;
   }
@@ -1298,12 +1329,24 @@ var MailMaskPartner = class {
     return (await this.request("GET", `${PARTNER_ROUTES.balanceMovements.path}${qs ? `?${qs}` : ""}`)).data;
   }
   /**
-   * Liga de MercadoPago para recargar saldo (pago único, $500 a $100,000 MXN). El saldo sube cuando
-   * MercadoPago confirma el pago, no al crear la liga. Abre `initPoint` en el navegador de quien paga.
+   * Liga de MercadoPago para recargar saldo (pago único; `amount` en unidades enteras de tu moneda:
+   * MXN 500 a 100,000, USD 29 a 5,500). El saldo sube cuando MercadoPago confirma el pago, no al
+   * crear la liga. Abre `initPoint` en el navegador de quien paga.
    */
   async topup(input) {
     return (await this.request("POST", PARTNER_ROUTES.topup.path, input)).data;
   }
+  /** La recarga automática mensual: `off`, `pending` (falta autorizarla) o `active`. */
+  async autoTopup() {
+    return (await this.request("GET", PARTNER_ROUTES.getAutoTopup.path)).data;
+  }
+  /**
+   * Prende o cambia (`amount` entero de tu moneda) la recarga automática mensual, o la apaga
+   * (`amount: null`). Al prenderla o cambiarla devuelve `initPoint`: ábrelo para autorizar el cobro.
+   */
+  async setAutoTopup(input) {
+    return (await this.request("PUT", PARTNER_ROUTES.setAutoTopup.path, input)).data;
+  }
   /** Uso del mes (`YYYY-MM`, default el mes en curso UTC): tenants activos y envíos. */
   async usage(opts = {}) {
     const q = opts.month ? `?month=${encodeURIComponent(opts.month)}` : "";
@@ -1504,6 +1547,10 @@ var MailMaskPartnerAdmin = class {
   setReputationPolicy(partnerId, policy) {
     return this.req("setReputationPolicy", { partnerId }, { policy });
   }
+  /** Sólo MailMask (admin): moneda del saldo (MXN o USD); sólo antes de cualquier movimiento aparte de la bienvenida. */
+  setCurrency(partnerId, currency) {
+    return this.req("setCurrency", { partnerId }, { currency });
+  }
   /** Sólo MailMask (admin): levanta cualquier pausa, también la de reputación. */
   resumeTenant(partnerId, externalId) {
     return this.req("resumeTenant", { partnerId, externalId });
@@ -1535,6 +1582,14 @@ var MailMaskPartnerAdmin = class {
   topup(partnerId, input) {
     return this.req("topup", { partnerId }, input);
   }
+  /** La recarga automática mensual del partner (dueño o MailMask). */
+  getAutoTopup(partnerId) {
+    return this.req("getAutoTopup", { partnerId });
+  }
+  /** Prende, cambia (`amount`) o apaga (`null`) la recarga automática; trae `initPoint` al prenderla. */
+  setAutoTopup(partnerId, input) {
+    return this.req("setAutoTopup", { partnerId }, input);
+  }
   listCredentials(partnerId) {
     return this.req("listCredentials", { partnerId });
   }
@@ -1553,6 +1608,7 @@ var MailMaskPartnerAdmin = class {
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  AUTO_TOPUP_SUGGESTIONS,
   AuthError,
   BALANCE_LOW_FRACTION,
   BALANCE_MOVEMENT_KINDS,
@@ -1577,8 +1633,10 @@ var MailMaskPartnerAdmin = class {
   NotFoundError,
   PARTNER_ADMIN_ROUTES,
   PARTNER_API_PREFIX,
+  PARTNER_CURRENCIES,
   PARTNER_ERROR_STATUS,
   PARTNER_HEADERS,
+  PARTNER_PRICES,
   PARTNER_PRICE_PER_EMAIL_CENTS,
   PARTNER_ROUTES,
   PARTNER_SIGNATURE_TOLERANCE_S,
@@ -1607,6 +1665,7 @@ var MailMaskPartnerAdmin = class {
   WEBHOOK_TOLERANCE_MS,
   createWebhookHandler,
   estimateSendDays,
+  formatMoney,
   isValidExternalId,
   isValidFallbackLabel,
   partnerSignatureBase,

package/dist/index.js

@@ -662,7 +662,7 @@ var MAX_BATCH_RECIPIENTS = 1e4;
 var MAX_TAGS = 10;
 var TAG_RE = /^[A-Za-z0-9_-]{1,64}$/;
 var TENANT_DAILY_LIMIT_START = 2e3;
-var TENANT_DAILY_LIMIT_MAX = 5e4;
+var TENANT_DAILY_LIMIT_MAX = 2e4;
 var TENANT_WARMUP_STEP_DAYS = 7;
 function warmupLimit(step) {
   return Math.min(TENANT_DAILY_LIMIT_MAX, TENANT_DAILY_LIMIT_START * 2 ** Math.max(0, step));
@@ -750,18 +750,32 @@ function personalizePartnerMessage(input) {
     ...text !== void 0 ? { text: renderTemplate(text, vars) } : {}
   };
 }
-var PARTNER_PRICE_PER_EMAIL_CENTS = 6;
-var PARTNER_TENANT_MONTH_CENTS = 4900;
-var PARTNER_WELCOME_CENTS = 5e4;
-var PARTNER_TOPUP_MIN_CENTS = 5e4;
-var PARTNER_TOPUP_MAX_CENTS = 1e7;
+var PARTNER_CURRENCIES = ["MXN", "USD"];
+var PARTNER_PRICES = {
+  MXN: { perEmailCents: 6, tenantMonthCents: 4900, welcomeCents: 5e4, topupMinCents: 5e4, topupMaxCents: 1e7 },
+  USD: { perEmailCents: 0.35, tenantMonthCents: 290, welcomeCents: 2900, topupMinCents: 2900, topupMaxCents: 55e4 }
+};
+var PARTNER_PRICE_PER_EMAIL_CENTS = PARTNER_PRICES.MXN.perEmailCents;
+var PARTNER_TENANT_MONTH_CENTS = PARTNER_PRICES.MXN.tenantMonthCents;
+var PARTNER_WELCOME_CENTS = PARTNER_PRICES.MXN.welcomeCents;
+var PARTNER_TOPUP_MIN_CENTS = PARTNER_PRICES.MXN.topupMinCents;
+var PARTNER_TOPUP_MAX_CENTS = PARTNER_PRICES.MXN.topupMaxCents;
+function formatMoney(cents, currency) {
+  const v = Math.abs(cents) / 100;
+  const decimals = v !== 0 && v < 0.01 ? 4 : 2;
+  const n = v.toLocaleString("en-US", { minimumFractionDigits: decimals, maximumFractionDigits: decimals });
+  return `${cents < 0 ? "\u2212" : ""}$${n} ${currency}`;
+}
 var BALANCE_LOW_FRACTION = 0.2;
 var BALANCE_MOVEMENT_KINDS = ["topup", "send", "tenant_fee", "refund", "adjust"];
+var AUTO_TOPUP_SUGGESTIONS = { MXN: [500, 1e3, 2500], USD: [29, 59, 149] };
 var PARTNER_WEBHOOK_EVENTS = [
   "email.sent",
   "email.delivered",
   "email.bounced",
   "email.complained",
+  "email.opened",
+  "email.clicked",
   "email.received",
   "contact.unsubscribed",
   "tenant.paused",
@@ -803,6 +817,8 @@ var PARTNER_ROUTES = {
   balance: { method: "GET", path: "/balance" },
   balanceMovements: { method: "GET", path: "/balance/movements" },
   topup: { method: "POST", path: "/topup" },
+  getAutoTopup: { method: "GET", path: "/auto-topup" },
+  setAutoTopup: { method: "PUT", path: "/auto-topup" },
   getWebhook: { method: "GET", path: "/webhook" },
   setWebhook: { method: "PUT", path: "/webhook" },
   testWebhook: { method: "POST", path: "/webhook/test" },
@@ -824,6 +840,10 @@ var PARTNER_ADMIN_ROUTES = {
   adjustBalance: { method: "POST", path: "/api/partners/:partnerId/balance/adjust" },
   /** Recarga con MercadoPago desde la sesión del dueño (misma respuesta que `POST /topup`). */
   topup: { method: "POST", path: "/api/partners/:partnerId/topup" },
+  getAutoTopup: { method: "GET", path: "/api/partners/:partnerId/auto-topup" },
+  setAutoTopup: { method: "PUT", path: "/api/partners/:partnerId/auto-topup" },
+  /** Sólo MailMask: moneda del saldo, mientras no haya más movimientos que la bienvenida. */
+  setCurrency: { method: "PUT", path: "/api/partners/:partnerId/currency" },
   /** Sólo MailMask: fija (o quita, con `null`) el límite diario de un tenant. Devuelve el `Tenant`. */
   setTenantDailyLimit: { method: "PUT", path: "/api/partners/:partnerId/tenants/:externalId/daily-limit" },
   listCredentials: { method: "GET", path: "/api/partners/:partnerId/credentials" },
@@ -965,6 +985,10 @@ var InsufficientBalanceError = class extends PartnerApiError {
   get requiredCents() {
     return this.body.requiredCents;
   }
+  /** Moneda de los dos montos de arriba. */
+  get currency() {
+    return this.body.currency;
+  }
 };
 var NetworkError = class extends PartnerApiError {
   constructor(message, cause) {
@@ -1187,7 +1211,10 @@ var MailMaskPartner = class {
     );
     return { ...data, idempotencyKey, replayed: meta.idempotentReplayed };
   }
-  /** Estado de un lote (`batchId` del resultado de `batch`): envíos y, después, entregas, rebotes, quejas y bajas. */
+  /**
+   * Estado de un lote (`batchId` del resultado de `batch`): envíos y, después, entregas, rebotes, quejas
+   * y bajas; con `track: true`, también aperturas, clics, tasas y `topLinks`.
+   */
   async batchStatus(externalId, batchId) {
     return (await this.request("GET", routePath(PARTNER_ROUTES.getBatch.path, { externalId, batchId }))).data;
   }
@@ -1205,12 +1232,24 @@ var MailMaskPartner = class {
     return (await this.request("GET", `${PARTNER_ROUTES.balanceMovements.path}${qs ? `?${qs}` : ""}`)).data;
   }
   /**
-   * Liga de MercadoPago para recargar saldo (pago único, $500 a $100,000 MXN). El saldo sube cuando
-   * MercadoPago confirma el pago, no al crear la liga. Abre `initPoint` en el navegador de quien paga.
+   * Liga de MercadoPago para recargar saldo (pago único; `amount` en unidades enteras de tu moneda:
+   * MXN 500 a 100,000, USD 29 a 5,500). El saldo sube cuando MercadoPago confirma el pago, no al
+   * crear la liga. Abre `initPoint` en el navegador de quien paga.
    */
   async topup(input) {
     return (await this.request("POST", PARTNER_ROUTES.topup.path, input)).data;
   }
+  /** La recarga automática mensual: `off`, `pending` (falta autorizarla) o `active`. */
+  async autoTopup() {
+    return (await this.request("GET", PARTNER_ROUTES.getAutoTopup.path)).data;
+  }
+  /**
+   * Prende o cambia (`amount` entero de tu moneda) la recarga automática mensual, o la apaga
+   * (`amount: null`). Al prenderla o cambiarla devuelve `initPoint`: ábrelo para autorizar el cobro.
+   */
+  async setAutoTopup(input) {
+    return (await this.request("PUT", PARTNER_ROUTES.setAutoTopup.path, input)).data;
+  }
   /** Uso del mes (`YYYY-MM`, default el mes en curso UTC): tenants activos y envíos. */
   async usage(opts = {}) {
     const q = opts.month ? `?month=${encodeURIComponent(opts.month)}` : "";
@@ -1411,6 +1450,10 @@ var MailMaskPartnerAdmin = class {
   setReputationPolicy(partnerId, policy) {
     return this.req("setReputationPolicy", { partnerId }, { policy });
   }
+  /** Sólo MailMask (admin): moneda del saldo (MXN o USD); sólo antes de cualquier movimiento aparte de la bienvenida. */
+  setCurrency(partnerId, currency) {
+    return this.req("setCurrency", { partnerId }, { currency });
+  }
   /** Sólo MailMask (admin): levanta cualquier pausa, también la de reputación. */
   resumeTenant(partnerId, externalId) {
     return this.req("resumeTenant", { partnerId, externalId });
@@ -1442,6 +1485,14 @@ var MailMaskPartnerAdmin = class {
   topup(partnerId, input) {
     return this.req("topup", { partnerId }, input);
   }
+  /** La recarga automática mensual del partner (dueño o MailMask). */
+  getAutoTopup(partnerId) {
+    return this.req("getAutoTopup", { partnerId });
+  }
+  /** Prende, cambia (`amount`) o apaga (`null`) la recarga automática; trae `initPoint` al prenderla. */
+  setAutoTopup(partnerId, input) {
+    return this.req("setAutoTopup", { partnerId }, input);
+  }
   listCredentials(partnerId) {
     return this.req("listCredentials", { partnerId });
   }
@@ -1459,6 +1510,7 @@ var MailMaskPartnerAdmin = class {
   }
 };
 export {
+  AUTO_TOPUP_SUGGESTIONS,
   AuthError,
   BALANCE_LOW_FRACTION,
   BALANCE_MOVEMENT_KINDS,
@@ -1483,8 +1535,10 @@ export {
   NotFoundError,
   PARTNER_ADMIN_ROUTES,
   PARTNER_API_PREFIX,
+  PARTNER_CURRENCIES,
   PARTNER_ERROR_STATUS,
   PARTNER_HEADERS,
+  PARTNER_PRICES,
   PARTNER_PRICE_PER_EMAIL_CENTS,
   PARTNER_ROUTES,
   PARTNER_SIGNATURE_TOLERANCE_S,
@@ -1513,6 +1567,7 @@ export {
   WEBHOOK_TOLERANCE_MS,
   createWebhookHandler,
   estimateSendDays,
+  formatMoney,
   isValidExternalId,
   isValidFallbackLabel,
   partnerSignatureBase,

package/dist/partner-contract.d.ts

@@ -86,9 +86,11 @@ export interface PartnerErrorBody {
     limit?: number;
     sentToday?: number;
     resetsAt?: string;
-    /** Sólo en `insufficient_balance`: saldo actual y lo que pedía el envío (centavos MXN). */
+    /** Sólo en `insufficient_balance`: saldo actual y lo que pedía el envío (centavos de `currency`). */
     balanceCents?: number;
     requiredCents?: number;
+    /** Moneda de `balanceCents` y `requiredCents`. */
+    currency?: PartnerCurrency;
     /** Sólo en `recipient_suppressed`. */
     reason?: SuppressionReason;
     stream?: MessageStream;
@@ -128,7 +130,7 @@ export interface Tenant {
  * regresa al inicio al reanudar. No hay tope mensual: el saldo es el otro freno.
  */
 export declare const TENANT_DAILY_LIMIT_START = 2000;
-export declare const TENANT_DAILY_LIMIT_MAX = 50000;
+export declare const TENANT_DAILY_LIMIT_MAX = 20000;
 export declare const TENANT_WARMUP_STEP_DAYS = 7;
 /** El límite del escalón `step` (0 = inicio). */
 export declare function warmupLimit(step: number): number;
@@ -334,6 +336,8 @@ export interface SendRequest {
     vars?: TemplateVars;
     /** Reintentar con la misma llave en 24 h devuelve la respuesta guardada sin volver a enviar. */
     idempotencyKey?: string;
+    /** Mide aperturas y clics (ver `track` en `BatchRequest`). Default `false`. */
+    track?: boolean;
 }
 /** `POST /tenants/:externalId/send` — 200. Con `Idempotent-Replayed: true` si fue repetición. */
 export interface SendResponse {
@@ -366,6 +370,21 @@ export interface BatchRequest {
     /** Default `broadcast` (lleva baja de un clic por destinatario). */
     stream?: MessageStream;
     idempotencyKey?: string;
+    /**
+     * Mide aperturas y clics: SES agrega un pixel invisible y reescribe cada liga del `html` para
+     * pasar por su redirector (el `text` no cambia). Llegan `email.opened`/`email.clicked` (la primera
+     * vez por correo) y suben `opened`, `clicked` y `topLinks` del `BatchStatus`. Default `false`: sin
+     * él el correo sale sin pixel y con las ligas intactas.
+     */
+    track?: boolean;
+}
+/** Una liga del lote con sus clics. `url` va sin `utm_*`, `fbclid` ni `gclid` (agrupa variantes). */
+export interface BatchTopLink {
+    url: string;
+    /** Clics totales (una persona que hace clic dos veces cuenta dos). */
+    clicks: number;
+    /** Correos distintos que hicieron clic en esta liga. */
+    uniqueClicks: number;
 }
 export type BatchState = "queued" | "processing" | "completed" | "failed";
 export interface BatchStatus {
@@ -385,6 +404,21 @@ export interface BatchStatus {
     bounced: number;
     complained: number;
     unsubscribed: number;
+    /** El lote se mandó con `track: true`. Sin él, los números de seguimiento se quedan en 0. */
+    track: boolean;
+    /**
+     * Correos del lote abiertos al menos una vez (únicos). Inflado: Apple Mail (Mail Privacy
+     * Protection) y algunos filtros abren el pixel solos. Para decidir, usa los clics.
+     */
+    opened: number;
+    /** Correos del lote con al menos un clic (únicos). Excluye la liga de baja. */
+    clicked: number;
+    /** `opened` / `delivered` (o / `sent` mientras `delivered` sea 0), de 0 a 1 con 4 decimales. */
+    openRate: number;
+    /** `clicked` sobre la misma base que `openRate`. */
+    clickRate: number;
+    /** Hasta 10 ligas con más clics, de más a menos. */
+    topLinks: BatchTopLink[];
     lastError: string | null;
     createdAt: string;
     completedAt: string | null;
@@ -422,20 +456,37 @@ export interface UsageResponse {
 }
 /**
  * El partner paga por adelantado: cada correo y la cuota mensual de cada tenant activo se
- * descuentan de un saldo que se recarga con MercadoPago (`POST /topup`). Todo en centavos de MXN.
+ * descuentan de un saldo que se recarga con MercadoPago (`POST /topup`). El saldo es en la moneda
+ * del partner (MXN o USD) y es la única unidad: no hay «créditos». Todos los montos `*Cents` son
+ * centavos de esa moneda y pueden traer decimales (en USD un correo cuesta 0.35 centavos; por
+ * dentro se lleva en milésimas de centavo). Se muestran con 2 decimales.
  */
-/** Precio por correo enviado (por destinatario). */
-export declare const PARTNER_PRICE_PER_EMAIL_CENTS = 6;
-/**
- * Cuota mensual por tenant activo. Activo = envía ese mes: se descuenta con su primer envío del
- * mes (UTC), una sola vez, así que un tenant dormido no cuesta nada.
- */
-export declare const PARTNER_TENANT_MONTH_CENTS = 4900;
-/** Saldo de bienvenida con el que nace todo partner (`adjust`, idemKey `welcome:<partnerId>`). */
-export declare const PARTNER_WELCOME_CENTS = 50000;
-/** Recarga mínima y máxima por pago. */
-export declare const PARTNER_TOPUP_MIN_CENTS = 50000;
-export declare const PARTNER_TOPUP_MAX_CENTS = 10000000;
+export type PartnerCurrency = "MXN" | "USD";
+export declare const PARTNER_CURRENCIES: readonly PartnerCurrency[];
+export interface PartnerPrices {
+    /** Por correo enviado (por destinatario). */
+    perEmailCents: number;
+    /**
+     * Cuota mensual por tenant activo. Activo = envía ese mes: se descuenta con su primer envío del
+     * mes (UTC), una sola vez, así que un tenant dormido no cuesta nada.
+     */
+    tenantMonthCents: number;
+    /** Saldo de bienvenida con el que nace el partner (`adjust`, idemKey `welcome:<partnerId>`). */
+    welcomeCents: number;
+    /** Recarga mínima y máxima por pago (enteros de la moneda × 100). */
+    topupMinCents: number;
+    topupMaxCents: number;
+}
+/** Precios por moneda. USD = MXN redondeado; se cobra en MXN por MercadoPago con el tipo de cambio. */
+export declare const PARTNER_PRICES: Record<PartnerCurrency, PartnerPrices>;
+/** Los de MXN, con su nombre de antes (0.7). */
+export declare const PARTNER_PRICE_PER_EMAIL_CENTS: number;
+export declare const PARTNER_TENANT_MONTH_CENTS: number;
+export declare const PARTNER_WELCOME_CENTS: number;
+export declare const PARTNER_TOPUP_MIN_CENTS: number;
+export declare const PARTNER_TOPUP_MAX_CENTS: number;
+/** `$1,234.50 USD`: 2 decimales (4 si el monto es menor a un centavo, como el precio por correo en USD). */
+export declare function formatMoney(cents: number, currency: PartnerCurrency): string;
 /** `balance.low` sale cuando el saldo baja del 20 % de la última recarga (una vez por recarga). */
 export declare const BALANCE_LOW_FRACTION = 0.2;
 export type BalanceMovementKind = "topup" | "send" | "tenant_fee" | "refund" | "adjust";
@@ -455,14 +506,11 @@ export interface BalanceMovement {
 }
 /** `GET /balance` */
 export interface BalanceResponse {
-    currency: "MXN";
+    /** La moneda del saldo y de todos los montos de esta respuesta. */
+    currency: PartnerCurrency;
     /** Sin saldo suficiente el envío se rechaza (402 `insufficient_balance`) y el lote espera. Siempre. */
     balanceCents: number;
-    prices: {
-        perEmailCents: number;
-        tenantMonthCents: number;
-        topupMinCents: number;
-    };
+    prices: PartnerPrices;
     lastTopup: {
         amountCents: number;
         at: string;
@@ -486,6 +534,8 @@ export interface BalanceMovementsQuery {
     kind?: BalanceMovementKind[];
 }
 export interface BalanceMovementsResponse {
+    /** La moneda de los montos. */
+    currency: PartnerCurrency;
     movements: BalanceMovement[];
     nextCursor: string | null;
 }
@@ -494,16 +544,62 @@ export interface BalanceMovementsResponse {
  * el pago (webhook), no al crear la liga. `returnUrl` (https) es a dónde regresa el navegador.
  */
 export interface TopupRequest {
-    /** Pesos MXN enteros, 500 a 100,000. */
-    amountMxn: number;
+    /**
+     * Unidades enteras de la moneda del partner (MXN: 500 a 100,000; USD: 29 a 5,500). En USD
+     * MercadoPago cobra el equivalente en MXN con el tipo de cambio de MailMask y se abona lo pedido
+     * en USD.
+     */
+    amount?: number;
+    /** Lo mismo que `amount`, sólo para partners en MXN (0.7). */
+    amountMxn?: number;
     returnUrl?: string;
 }
 export interface TopupResponse {
     topupId: string;
+    /** Lo que se abona al saldo, en la moneda del partner. */
     amountCents: number;
+    currency: PartnerCurrency;
+    /** Lo que cobra MercadoPago, en centavos MXN (igual a `amountCents` si el partner es MXN). */
+    chargeMxnCents: number;
+    /** MXN por USD con que se cotizó; null en MXN. */
+    fxRate: number | null;
     /** Abre esto en el navegador de quien paga. */
     initPoint: string;
 }
+/**
+ * Recarga automática mensual: un cobro de MercadoPago cada mes (preapproval con la tarjeta del
+ * dueño) que abona `amountCents` al saldo con nota «Recarga automática». En USD MercadoPago cobra
+ * `chargeMxnCents` (fijado al activarla) y se abona lo elegido en USD.
+ */
+export interface AutoTopup {
+    /** off = apagada; pending = falta autorizarla en MercadoPago (`initPoint`); active = cobra cada mes. */
+    status: "off" | "pending" | "active";
+    currency: PartnerCurrency;
+    amountCents: number | null;
+    chargeMxnCents: number | null;
+    nextChargeAt: string | null;
+    lastChargeAt: string | null;
+    /** Cobros rechazados seguidos (se reinicia con uno aprobado). */
+    failedCharges: number;
+    lastError: string | null;
+    /** Sólo en la respuesta de prenderla o cambiarla: ábrelo para autorizar el cobro mensual. */
+    initPoint?: string;
+}
+/**
+ * `PUT /auto-topup` — `amount` en unidades enteras de la moneda (mismo rango que `/topup`) la prende
+ * o cambia (cancela la anterior y crea otra); `null` la apaga.
+ */
+export interface SetAutoTopupRequest {
+    amount: number | null;
+    /**
+     * Correo de la cuenta de MercadoPago con que se paga, si no es el del dueño en MailMask
+     * (MercadoPago rechaza el de su propia cuenta cobradora).
+     */
+    payerEmail?: string;
+    returnUrl?: string;
+}
+/** Montos sugeridos para la recarga automática (unidades enteras). */
+export declare const AUTO_TOPUP_SUGGESTIONS: Record<PartnerCurrency, readonly number[]>;
 /**
  * `GET /api/partners/:partnerId/balance` (dueño o MailMask): el saldo, sus últimos 20 movimientos,
  * el partner (con `tenants` y `ownerEmail`) y si quien mira es de MailMask (ve abonar y el cobro).
@@ -520,6 +616,8 @@ export type PartnerBalanceDetail = BalanceResponse & {
     movements: BalanceMovement[];
     partner: PartnerSummary;
     tenants: PartnerDetailTenant[];
+    /** La recarga automática mensual. */
+    autoTopup: AutoTopup;
     staff: boolean;
 };
 /** `PUT /api/partners/:partnerId/tenants/:externalId/daily-limit` — sólo MailMask: tope fijo o `null` (vuelve al calentamiento). */
@@ -528,7 +626,7 @@ export interface SetTenantDailyLimitRequest {
 }
 /** `POST /api/partners/:partnerId/balance/adjust` — sólo MailMask (admin): abono o cargo manual. */
 export interface AdjustBalanceRequest {
-    /** Centavos MXN, distinto de 0 (negativo = cargo). */
+    /** Centavos enteros de la moneda del partner, distinto de 0 (negativo = cargo). */
     amountCents: number;
     note: string;
     /** Repetir con la misma llave no vuelve a abonar. */
@@ -567,7 +665,7 @@ export interface RotateWebhookSecretResponse {
 export interface TestWebhookResponse {
     deliveryId: string;
 }
-export declare const PARTNER_WEBHOOK_EVENTS: readonly ["email.sent", "email.delivered", "email.bounced", "email.complained", "email.received", "contact.unsubscribed", "tenant.paused", "tenant.resumed", "domain.verified", "balance.low", "batch.throttled"];
+export declare const PARTNER_WEBHOOK_EVENTS: readonly ["email.sent", "email.delivered", "email.bounced", "email.complained", "email.opened", "email.clicked", "email.received", "contact.unsubscribed", "tenant.paused", "tenant.resumed", "domain.verified", "balance.low", "batch.throttled"];
 export type PartnerWebhookEvent = typeof PARTNER_WEBHOOK_EVENTS[number];
 /** Headers de cada entrega al webhook del partner (los mismos que los webhooks de dominio). */
 export declare const WEBHOOK_HEADERS: {
@@ -614,6 +712,24 @@ export interface PartnerEventData {
         recipient: string;
         feedbackType: string | null;
     };
+    /**
+     * Primera apertura de un correo enviado con `track: true` (una sola vez por correo). Inflado por
+     * Apple Mail Privacy Protection: decide por `email.clicked`.
+     */
+    "email.opened": EmailEventBase & {
+        recipient: string;
+        batchId: string | null;
+        openedAt: string;
+        userAgent: string | null;
+    };
+    /** Primer clic de un correo enviado con `track: true` (una sola vez por correo). `url` es la liga original. */
+    "email.clicked": EmailEventBase & {
+        recipient: string;
+        batchId: string | null;
+        url: string;
+        clickedAt: string;
+        userAgent: string | null;
+    };
     "email.received": {
         domain: string;
         from: string;
@@ -650,6 +766,7 @@ export interface PartnerEventData {
         balanceCents: number;
         thresholdCents: number;
         lastTopupCents: number;
+        currency: PartnerCurrency;
     };
     /** Un lote llegó al límite diario del tenant: sigue solo en `resumesAt`. Una vez por lote. */
     "batch.throttled": {
@@ -696,8 +813,9 @@ export interface PartnerSummary {
     effectiveReputationPolicy: ReputationPolicy;
     /** Zona de respaldo (`marketing.denik.me`); null = sin zona. Ver `FallbackZone`. */
     fallbackZone: string | null;
-    /** Saldo prepagado (centavos MXN). Ver `BalanceResponse`. */
+    /** Saldo prepagado, en centavos de `currency`. Ver `BalanceResponse`. */
     balanceCents: number;
+    currency: PartnerCurrency;
     /** Sólo en `GET /api/partners?all=1` (MailMask, admin): tenants totales y activos del mes. */
     tenants?: {
         total: number;
@@ -713,6 +831,15 @@ export interface CreatePartnerRequest {
     ownerEmail: string;
     plan?: Partial<PartnerSummary["plan"]>;
     reputationPolicy?: ReputationPolicy | null;
+    /** Moneda del saldo; default MXN. Nace con la bienvenida de esa moneda. */
+    currency?: PartnerCurrency;
+}
+/**
+ * `PUT /api/partners/:partnerId/currency` — sólo MailMask, y sólo mientras el partner no tenga más
+ * movimientos que la bienvenida (que se cambia por la de la nueva moneda).
+ */
+export interface SetPartnerCurrencyRequest {
+    currency: PartnerCurrency;
 }
 /** `PUT /api/partners/:partnerId/reputation-policy` — sólo MailMask (admin); null = automática. */
 export interface SetReputationPolicyRequest {
@@ -832,6 +959,14 @@ export declare const PARTNER_ROUTES: {
         readonly method: "POST";
         readonly path: "/topup";
     };
+    readonly getAutoTopup: {
+        readonly method: "GET";
+        readonly path: "/auto-topup";
+    };
+    readonly setAutoTopup: {
+        readonly method: "PUT";
+        readonly path: "/auto-topup";
+    };
     readonly getWebhook: {
         readonly method: "GET";
         readonly path: "/webhook";
@@ -893,6 +1028,19 @@ export declare const PARTNER_ADMIN_ROUTES: {
         readonly method: "POST";
         readonly path: "/api/partners/:partnerId/topup";
     };
+    readonly getAutoTopup: {
+        readonly method: "GET";
+        readonly path: "/api/partners/:partnerId/auto-topup";
+    };
+    readonly setAutoTopup: {
+        readonly method: "PUT";
+        readonly path: "/api/partners/:partnerId/auto-topup";
+    };
+    /** Sólo MailMask: moneda del saldo, mientras no haya más movimientos que la bienvenida. */
+    readonly setCurrency: {
+        readonly method: "PUT";
+        readonly path: "/api/partners/:partnerId/currency";
+    };
     /** Sólo MailMask: fija (o quita, con `null`) el límite diario de un tenant. Devuelve el `Tenant`. */
     readonly setTenantDailyLimit: {
         readonly method: "PUT";

package/dist/partner.d.ts

@@ -1,5 +1,5 @@
 import { MailMaskError } from "./client.js";
-import type { TemplateVars, PartnerSummary, CreatePartnerRequest, ReputationPolicy, ListCredentialsResponse, CreateCredentialRequest, CreateCredentialResponse, RotateCredentialRequest, RotateCredentialResponse, RevokeCredentialResponse, PartnerErrorBody, PartnerErrorCode, Tenant, PutTenantRequest, ListTenantsQuery, ListTenantsResponse, DeleteTenantResponse, PartnerDomain, SendRequest, SendResponse, BatchRequest, BatchStatus, UsageResponse, WebhookConfig, SetWebhookRequest, SetWebhookResponse, TestWebhookResponse, PartnerWebhookPayload, RotateWebhookSecretRequest, RotateWebhookSecretResponse, MessageStream, SuppressionReason, FallbackZone, BalanceResponse, BalanceMovementsQuery, BalanceMovementsResponse, TopupRequest, TopupResponse, PartnerBalanceDetail, AdjustBalanceRequest } from "./partner-contract.js";
+import type { TemplateVars, PartnerSummary, CreatePartnerRequest, ReputationPolicy, ListCredentialsResponse, CreateCredentialRequest, CreateCredentialResponse, RotateCredentialRequest, RotateCredentialResponse, RevokeCredentialResponse, PartnerErrorBody, PartnerErrorCode, Tenant, PutTenantRequest, ListTenantsQuery, ListTenantsResponse, DeleteTenantResponse, PartnerDomain, SendRequest, SendResponse, BatchRequest, BatchStatus, UsageResponse, WebhookConfig, SetWebhookRequest, SetWebhookResponse, TestWebhookResponse, PartnerWebhookPayload, RotateWebhookSecretRequest, RotateWebhookSecretResponse, MessageStream, SuppressionReason, FallbackZone, BalanceResponse, BalanceMovementsQuery, BalanceMovementsResponse, TopupRequest, TopupResponse, PartnerBalanceDetail, AdjustBalanceRequest, PartnerCurrency, AutoTopup, SetAutoTopupRequest } from "./partner-contract.js";
 export * from "./partner-contract.js";
 /**
  * Discriminante estable de los errores de partners, para un `switch` sin cadenas de `instanceof`.
@@ -111,13 +111,15 @@ export declare class DailyLimitError extends QuotaError {
     get sentToday(): number | undefined;
 }
 /**
- * 402 `insufficient_balance`: el saldo prepagado no alcanza. No se reintenta: recarga con `partner.topup()`. Trae `balanceCents` y `requiredCents`.
+ * 402 `insufficient_balance`: el saldo prepagado no alcanza. No se reintenta: recarga con `partner.topup()`. Trae `balanceCents`, `requiredCents` y `currency`.
  */
 export declare class InsufficientBalanceError extends PartnerApiError {
     name: string;
     kind: PartnerErrorKind;
     get balanceCents(): number | undefined;
     get requiredCents(): number | undefined;
+    /** Moneda de los dos montos de arriba. */
+    get currency(): PartnerCurrency | undefined;
 }
 /** No hubo respuesta: DNS, conexión rechazada o cortada. `status` 0. */
 export declare class NetworkError extends PartnerApiError {
@@ -235,17 +237,28 @@ export declare class MailMaskPartner {
         idempotencyKey: string;
         replayed: boolean;
     }>;
-    /** Estado de un lote (`batchId` del resultado de `batch`): envíos y, después, entregas, rebotes, quejas y bajas. */
+    /**
+     * Estado de un lote (`batchId` del resultado de `batch`): envíos y, después, entregas, rebotes, quejas
+     * y bajas; con `track: true`, también aperturas, clics, tasas y `topLinks`.
+     */
     batchStatus(externalId: string, batchId: string): Promise<BatchStatus>;
     /** Saldo prepagado: saldo, precios, última recarga y consumo del mes (centavos MXN). */
     balance(): Promise<BalanceResponse>;
     /** Movimientos del saldo, del más nuevo al más viejo; pagina con `nextCursor`. */
     balanceMovements(query?: BalanceMovementsQuery): Promise<BalanceMovementsResponse>;
     /**
-     * Liga de MercadoPago para recargar saldo (pago único, $500 a $100,000 MXN). El saldo sube cuando
-     * MercadoPago confirma el pago, no al crear la liga. Abre `initPoint` en el navegador de quien paga.
+     * Liga de MercadoPago para recargar saldo (pago único; `amount` en unidades enteras de tu moneda:
+     * MXN 500 a 100,000, USD 29 a 5,500). El saldo sube cuando MercadoPago confirma el pago, no al
+     * crear la liga. Abre `initPoint` en el navegador de quien paga.
      */
     topup(input: TopupRequest): Promise<TopupResponse>;
+    /** La recarga automática mensual: `off`, `pending` (falta autorizarla) o `active`. */
+    autoTopup(): Promise<AutoTopup>;
+    /**
+     * Prende o cambia (`amount` entero de tu moneda) la recarga automática mensual, o la apaga
+     * (`amount: null`). Al prenderla o cambiarla devuelve `initPoint`: ábrelo para autorizar el cobro.
+     */
+    setAutoTopup(input: SetAutoTopupRequest): Promise<AutoTopup>;
     /** Uso del mes (`YYYY-MM`, default el mes en curso UTC): tenants activos y envíos. */
     usage(opts?: {
         month?: string;
@@ -380,6 +393,8 @@ export declare class MailMaskPartnerAdmin {
     createPartner(input: CreatePartnerRequest): Promise<PartnerSummary>;
     /** Sólo MailMask (admin); null = automática (Strict el primer mes, Standard después). */
     setReputationPolicy(partnerId: string, policy: ReputationPolicy | null): Promise<PartnerSummary>;
+    /** Sólo MailMask (admin): moneda del saldo (MXN o USD); sólo antes de cualquier movimiento aparte de la bienvenida. */
+    setCurrency(partnerId: string, currency: PartnerCurrency): Promise<PartnerSummary>;
     /** Sólo MailMask (admin): levanta cualquier pausa, también la de reputación. */
     resumeTenant(partnerId: string, externalId: string): Promise<Tenant>;
     /** Sólo MailMask: tope diario fijo del tenant, o `null` para volver al calentamiento. */
@@ -397,6 +412,10 @@ export declare class MailMaskPartnerAdmin {
     adjustBalance(partnerId: string, input: AdjustBalanceRequest): Promise<PartnerBalanceDetail>;
     /** Liga de MercadoPago para recargar, con la llave del dueño. */
     topup(partnerId: string, input: TopupRequest): Promise<TopupResponse>;
+    /** La recarga automática mensual del partner (dueño o MailMask). */
+    getAutoTopup(partnerId: string): Promise<AutoTopup>;
+    /** Prende, cambia (`amount`) o apaga (`null`) la recarga automática; trae `initPoint` al prenderla. */
+    setAutoTopup(partnerId: string, input: SetAutoTopupRequest): Promise<AutoTopup>;
     listCredentials(partnerId: string): Promise<ListCredentialsResponse>;
     /** El secreto `mms_…` viene UNA vez en la respuesta. */
     createCredential(partnerId: string, input?: CreateCredentialRequest): Promise<CreateCredentialResponse>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@easybits.cloud/mailmask",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "description": "Official SDK for the MailMask email alias/forwarding API",
   "type": "module",
   "main": "./dist/index.cjs",