@easybits.cloud/mailmask 0.6.1 → 0.8.0

package/dist/index.cjs

@@ -21,11 +21,15 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   AuthError: () => AuthError,
+  BALANCE_LOW_FRACTION: () => BALANCE_LOW_FRACTION,
+  BALANCE_MOVEMENT_KINDS: () => BALANCE_MOVEMENT_KINDS,
   ConflictError: () => ConflictError,
   DOMAIN_CLAIM_TTL_DAYS: () => DOMAIN_CLAIM_TTL_DAYS,
+  DailyLimitError: () => DailyLimitError,
   EXTERNAL_ID_RE: () => EXTERNAL_ID_RE,
   FALLBACK_LABEL_RE: () => FALLBACK_LABEL_RE,
   ForbiddenError: () => ForbiddenError,
+  InsufficientBalanceError: () => InsufficientBalanceError,
   MAX_BATCH_RECIPIENTS: () => MAX_BATCH_RECIPIENTS,
   MAX_TAGS: () => MAX_TAGS,
   MAX_TEMPLATE_VARS: () => MAX_TEMPLATE_VARS,
@@ -42,9 +46,14 @@ __export(index_exports, {
   PARTNER_API_PREFIX: () => PARTNER_API_PREFIX,
   PARTNER_ERROR_STATUS: () => PARTNER_ERROR_STATUS,
   PARTNER_HEADERS: () => PARTNER_HEADERS,
+  PARTNER_PRICE_PER_EMAIL_CENTS: () => PARTNER_PRICE_PER_EMAIL_CENTS,
   PARTNER_ROUTES: () => PARTNER_ROUTES,
   PARTNER_SIGNATURE_TOLERANCE_S: () => PARTNER_SIGNATURE_TOLERANCE_S,
+  PARTNER_TENANT_MONTH_CENTS: () => PARTNER_TENANT_MONTH_CENTS,
+  PARTNER_TOPUP_MAX_CENTS: () => PARTNER_TOPUP_MAX_CENTS,
+  PARTNER_TOPUP_MIN_CENTS: () => PARTNER_TOPUP_MIN_CENTS,
   PARTNER_WEBHOOK_EVENTS: () => PARTNER_WEBHOOK_EVENTS,
+  PARTNER_WELCOME_CENTS: () => PARTNER_WELCOME_CENTS,
   PartnerApiError: () => PartnerApiError,
   PausedError: () => PausedError,
   QuotaError: () => QuotaError,
@@ -55,12 +64,16 @@ __export(index_exports, {
   STRICT_FIRST_DAYS: () => STRICT_FIRST_DAYS,
   TAG_RE: () => TAG_RE,
   TEMPLATE_VAR_NAME_RE: () => TEMPLATE_VAR_NAME_RE,
+  TENANT_DAILY_LIMIT_MAX: () => TENANT_DAILY_LIMIT_MAX,
+  TENANT_DAILY_LIMIT_START: () => TENANT_DAILY_LIMIT_START,
+  TENANT_WARMUP_STEP_DAYS: () => TENANT_WARMUP_STEP_DAYS,
   TimeoutError: () => TimeoutError,
   UNSUBSCRIBE_URL_VAR: () => UNSUBSCRIBE_URL_VAR,
   ValidationError: () => ValidationError,
   WEBHOOK_HEADERS: () => WEBHOOK_HEADERS,
   WEBHOOK_TOLERANCE_MS: () => WEBHOOK_TOLERANCE_MS,
   createWebhookHandler: () => createWebhookHandler,
+  estimateSendDays: () => estimateSendDays,
   isValidExternalId: () => isValidExternalId,
   isValidFallbackLabel: () => isValidFallbackLabel,
   partnerSignatureBase: () => partnerSignatureBase,
@@ -73,6 +86,7 @@ __export(index_exports, {
   templateVarsProblem: () => templateVarsProblem,
   verifyWebhook: () => verifyWebhook,
   verifyWebhookSignature: () => verifyWebhookSignature,
+  warmupLimit: () => warmupLimit,
   webhookSignatureBase: () => webhookSignatureBase
 });
 module.exports = __toCommonJS(index_exports);
@@ -716,7 +730,17 @@ var PARTNER_ERROR_STATUS = {
   recipient_suppressed: 422,
   /** El tenant está en pausa (por MailMask o por el partner). No se manda nada hasta `resume`. */
   tenant_paused: 423,
-  /** Cuota mensual del tenant agotada. */
+  /**
+   * Saldo prepagado insuficiente (con `balanceCents` y `requiredCents`). No se reintenta: recarga
+   * con `POST /topup`.
+   */
+  insufficient_balance: 402,
+  /**
+   * El tenant llegó a su límite del día (con `limit`, `sentToday` y `resetsAt`, la medianoche UTC).
+   * Sólo en envíos sueltos: un lote no falla, espera al día siguiente (`batch.throttled`).
+   */
+  daily_limit: 429,
+  /** Ya no sale desde la 0.8 (no hay tope mensual); se deja para clientes viejos. */
   quota_exceeded: 429,
   /** Demasiadas peticiones; reintenta tras `Retry-After`. */
   rate_limited: 429,
@@ -730,6 +754,30 @@ function isValidExternalId(id) {
 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_WARMUP_STEP_DAYS = 7;
+function warmupLimit(step) {
+  return Math.min(TENANT_DAILY_LIMIT_MAX, TENANT_DAILY_LIMIT_START * 2 ** Math.max(0, step));
+}
+function estimateSendDays(s, recipients) {
+  let left = recipients - Math.max(0, s.dailyLimit - s.sentToday);
+  if (left <= 0) return 1;
+  let days = 1;
+  let limit = s.dailyLimit;
+  let nextAt = s.nextStepAt ? Date.parse(s.nextStepAt) : null;
+  let day = Date.parse(s.resetsAt);
+  while (left > 0 && days < 3650) {
+    while (nextAt !== null && nextAt <= day && limit < TENANT_DAILY_LIMIT_MAX && !s.fixed) {
+      limit = Math.min(TENANT_DAILY_LIMIT_MAX, limit * 2);
+      nextAt += TENANT_WARMUP_STEP_DAYS * 864e5;
+    }
+    left -= limit;
+    days++;
+    day += 864e5;
+  }
+  return days;
+}
 var DOMAIN_CLAIM_TTL_DAYS = 7;
 var FALLBACK_LABEL_RE = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
 var RESERVED_FALLBACK_LABELS = [
@@ -795,6 +843,13 @@ 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 BALANCE_LOW_FRACTION = 0.2;
+var BALANCE_MOVEMENT_KINDS = ["topup", "send", "tenant_fee", "refund", "adjust"];
 var PARTNER_WEBHOOK_EVENTS = [
   "email.sent",
   "email.delivered",
@@ -804,7 +859,9 @@ var PARTNER_WEBHOOK_EVENTS = [
   "contact.unsubscribed",
   "tenant.paused",
   "tenant.resumed",
-  "domain.verified"
+  "domain.verified",
+  "balance.low",
+  "batch.throttled"
 ];
 var WEBHOOK_HEADERS = {
   event: "X-MailMask-Event",
@@ -836,6 +893,9 @@ var PARTNER_ROUTES = {
   batch: { method: "POST", path: "/tenants/:externalId/batch" },
   getBatch: { method: "GET", path: "/tenants/:externalId/batch/:batchId" },
   usage: { method: "GET", path: "/usage" },
+  balance: { method: "GET", path: "/balance" },
+  balanceMovements: { method: "GET", path: "/balance/movements" },
+  topup: { method: "POST", path: "/topup" },
   getWebhook: { method: "GET", path: "/webhook" },
   setWebhook: { method: "PUT", path: "/webhook" },
   testWebhook: { method: "POST", path: "/webhook/test" },
@@ -851,6 +911,14 @@ var PARTNER_ADMIN_ROUTES = {
   setFallbackZone: { method: "PUT", path: "/api/partners/:partnerId/fallback-zone" },
   /** La zona de respaldo y si la delegación ya se ve en el DNS público. */
   getFallbackZone: { method: "GET", path: "/api/partners/:partnerId/fallback-zone" },
+  /** El saldo del partner (dueño o MailMask). */
+  getBalance: { method: "GET", path: "/api/partners/:partnerId/balance" },
+  /** Sólo MailMask (admin): abono o cargo manual (`adjust`). */
+  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" },
+  /** 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" },
   createCredential: { method: "POST", path: "/api/partners/:partnerId/credentials" },
   rotateCredential: { method: "POST", path: "/api/partners/:partnerId/credentials/:keyId/rotate" },
@@ -864,8 +932,8 @@ var PartnerApiError = class extends MailMaskError {
       code: body.code,
       requestId: meta.requestId,
       cause: meta.cause,
-      // `quota_exceeded` es un 429 que no se arregla reintentando: hasta el mes siguiente.
-      retryable: status === 0 || status >= 500 || status === 429 && body.code !== "quota_exceeded"
+      // `daily_limit` (y el viejo `quota_exceeded`) son 429 que no se arreglan reintentando: hasta mañana.
+      retryable: status === 0 || status >= 500 || status === 429 && body.code !== "quota_exceeded" && body.code !== "daily_limit"
     });
     this.kind = "unknown";
     this.name = "PartnerApiError";
@@ -968,6 +1036,29 @@ var RateLimitError = class extends QuotaError {
     this.kind = "rate_limit";
   }
 };
+var DailyLimitError = class extends QuotaError {
+  constructor() {
+    super(...arguments);
+    this.name = "DailyLimitError";
+    this.kind = "daily_limit";
+  }
+  get sentToday() {
+    return this.body.sentToday;
+  }
+};
+var InsufficientBalanceError = class extends PartnerApiError {
+  constructor() {
+    super(...arguments);
+    this.name = "InsufficientBalanceError";
+    this.kind = "insufficient_balance";
+  }
+  get balanceCents() {
+    return this.body.balanceCents;
+  }
+  get requiredCents() {
+    return this.body.requiredCents;
+  }
+};
 var NetworkError = class extends PartnerApiError {
   constructor(message, cause) {
     super(0, message, {}, { cause });
@@ -986,10 +1077,13 @@ function errorFor(status, body, fallback, meta = {}) {
   const msg = body.error || fallback;
   if (body.code === "reputation_hold") return new ReputationHoldError(status, msg, body, meta);
   if (body.code === "recipient_suppressed") return new RecipientSuppressedError(status, msg, body, meta);
+  if (status === 429 && body.code === "daily_limit") return new DailyLimitError(status, msg, body, meta);
   if (status === 429 && body.code !== "quota_exceeded") return new RateLimitError(status, msg, body, meta);
   switch (status) {
     case 401:
       return new AuthError(status, msg, body, meta);
+    case 402:
+      return new InsufficientBalanceError(status, msg, body, meta);
     case 403:
       return new ForbiddenError(status, msg, body, meta);
     case 404:
@@ -1190,6 +1284,26 @@ var MailMaskPartner = class {
   async batchStatus(externalId, batchId) {
     return (await this.request("GET", routePath(PARTNER_ROUTES.getBatch.path, { externalId, batchId }))).data;
   }
+  /** Saldo prepagado: saldo, precios, última recarga y consumo del mes (centavos MXN). */
+  async balance() {
+    return (await this.request("GET", PARTNER_ROUTES.balance.path)).data;
+  }
+  /** Movimientos del saldo, del más nuevo al más viejo; pagina con `nextCursor`. */
+  async balanceMovements(query = {}) {
+    const q = new URLSearchParams();
+    if (query.cursor) q.set("cursor", query.cursor);
+    if (query.limit !== void 0) q.set("limit", String(query.limit));
+    if (query.kind?.length) q.set("kind", query.kind.join(","));
+    const qs = q.toString();
+    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.
+   */
+  async topup(input) {
+    return (await this.request("POST", PARTNER_ROUTES.topup.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)}` : "";
@@ -1394,6 +1508,10 @@ var MailMaskPartnerAdmin = class {
   resumeTenant(partnerId, externalId) {
     return this.req("resumeTenant", { partnerId, externalId });
   }
+  /** Sólo MailMask: tope diario fijo del tenant, o `null` para volver al calentamiento. */
+  setTenantDailyLimit(partnerId, externalId, limit) {
+    return this.req("setTenantDailyLimit", { partnerId, externalId }, { limit });
+  }
   /**
    * Sólo MailMask (admin): crea o adopta la hosted zone de la zona de respaldo (`marketing.denik.me`)
    * y devuelve los NS que el partner tiene que delegar. Idempotente con la misma zona.
@@ -1405,6 +1523,18 @@ var MailMaskPartnerAdmin = class {
   getFallbackZone(partnerId) {
     return this.req("getFallbackZone", { partnerId });
   }
+  /** Saldo del partner con sus últimos 20 movimientos (dueño o MailMask). */
+  getBalance(partnerId) {
+    return this.req("getBalance", { partnerId });
+  }
+  /** Sólo MailMask (admin): abono (o cargo, negativo) manual. Con la misma `idempotencyKey` no se repite. */
+  adjustBalance(partnerId, input) {
+    return this.req("adjustBalance", { partnerId }, input);
+  }
+  /** Liga de MercadoPago para recargar, con la llave del dueño. */
+  topup(partnerId, input) {
+    return this.req("topup", { partnerId }, input);
+  }
   listCredentials(partnerId) {
     return this.req("listCredentials", { partnerId });
   }
@@ -1424,11 +1554,15 @@ var MailMaskPartnerAdmin = class {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AuthError,
+  BALANCE_LOW_FRACTION,
+  BALANCE_MOVEMENT_KINDS,
   ConflictError,
   DOMAIN_CLAIM_TTL_DAYS,
+  DailyLimitError,
   EXTERNAL_ID_RE,
   FALLBACK_LABEL_RE,
   ForbiddenError,
+  InsufficientBalanceError,
   MAX_BATCH_RECIPIENTS,
   MAX_TAGS,
   MAX_TEMPLATE_VARS,
@@ -1445,9 +1579,14 @@ var MailMaskPartnerAdmin = class {
   PARTNER_API_PREFIX,
   PARTNER_ERROR_STATUS,
   PARTNER_HEADERS,
+  PARTNER_PRICE_PER_EMAIL_CENTS,
   PARTNER_ROUTES,
   PARTNER_SIGNATURE_TOLERANCE_S,
+  PARTNER_TENANT_MONTH_CENTS,
+  PARTNER_TOPUP_MAX_CENTS,
+  PARTNER_TOPUP_MIN_CENTS,
   PARTNER_WEBHOOK_EVENTS,
+  PARTNER_WELCOME_CENTS,
   PartnerApiError,
   PausedError,
   QuotaError,
@@ -1458,12 +1597,16 @@ var MailMaskPartnerAdmin = class {
   STRICT_FIRST_DAYS,
   TAG_RE,
   TEMPLATE_VAR_NAME_RE,
+  TENANT_DAILY_LIMIT_MAX,
+  TENANT_DAILY_LIMIT_START,
+  TENANT_WARMUP_STEP_DAYS,
   TimeoutError,
   UNSUBSCRIBE_URL_VAR,
   ValidationError,
   WEBHOOK_HEADERS,
   WEBHOOK_TOLERANCE_MS,
   createWebhookHandler,
+  estimateSendDays,
   isValidExternalId,
   isValidFallbackLabel,
   partnerSignatureBase,
@@ -1476,5 +1619,6 @@ var MailMaskPartnerAdmin = class {
   templateVarsProblem,
   verifyWebhook,
   verifyWebhookSignature,
+  warmupLimit,
   webhookSignatureBase
 });

package/dist/index.js

@@ -637,7 +637,17 @@ var PARTNER_ERROR_STATUS = {
   recipient_suppressed: 422,
   /** El tenant está en pausa (por MailMask o por el partner). No se manda nada hasta `resume`. */
   tenant_paused: 423,
-  /** Cuota mensual del tenant agotada. */
+  /**
+   * Saldo prepagado insuficiente (con `balanceCents` y `requiredCents`). No se reintenta: recarga
+   * con `POST /topup`.
+   */
+  insufficient_balance: 402,
+  /**
+   * El tenant llegó a su límite del día (con `limit`, `sentToday` y `resetsAt`, la medianoche UTC).
+   * Sólo en envíos sueltos: un lote no falla, espera al día siguiente (`batch.throttled`).
+   */
+  daily_limit: 429,
+  /** Ya no sale desde la 0.8 (no hay tope mensual); se deja para clientes viejos. */
   quota_exceeded: 429,
   /** Demasiadas peticiones; reintenta tras `Retry-After`. */
   rate_limited: 429,
@@ -651,6 +661,30 @@ function isValidExternalId(id) {
 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_WARMUP_STEP_DAYS = 7;
+function warmupLimit(step) {
+  return Math.min(TENANT_DAILY_LIMIT_MAX, TENANT_DAILY_LIMIT_START * 2 ** Math.max(0, step));
+}
+function estimateSendDays(s, recipients) {
+  let left = recipients - Math.max(0, s.dailyLimit - s.sentToday);
+  if (left <= 0) return 1;
+  let days = 1;
+  let limit = s.dailyLimit;
+  let nextAt = s.nextStepAt ? Date.parse(s.nextStepAt) : null;
+  let day = Date.parse(s.resetsAt);
+  while (left > 0 && days < 3650) {
+    while (nextAt !== null && nextAt <= day && limit < TENANT_DAILY_LIMIT_MAX && !s.fixed) {
+      limit = Math.min(TENANT_DAILY_LIMIT_MAX, limit * 2);
+      nextAt += TENANT_WARMUP_STEP_DAYS * 864e5;
+    }
+    left -= limit;
+    days++;
+    day += 864e5;
+  }
+  return days;
+}
 var DOMAIN_CLAIM_TTL_DAYS = 7;
 var FALLBACK_LABEL_RE = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
 var RESERVED_FALLBACK_LABELS = [
@@ -716,6 +750,13 @@ 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 BALANCE_LOW_FRACTION = 0.2;
+var BALANCE_MOVEMENT_KINDS = ["topup", "send", "tenant_fee", "refund", "adjust"];
 var PARTNER_WEBHOOK_EVENTS = [
   "email.sent",
   "email.delivered",
@@ -725,7 +766,9 @@ var PARTNER_WEBHOOK_EVENTS = [
   "contact.unsubscribed",
   "tenant.paused",
   "tenant.resumed",
-  "domain.verified"
+  "domain.verified",
+  "balance.low",
+  "batch.throttled"
 ];
 var WEBHOOK_HEADERS = {
   event: "X-MailMask-Event",
@@ -757,6 +800,9 @@ var PARTNER_ROUTES = {
   batch: { method: "POST", path: "/tenants/:externalId/batch" },
   getBatch: { method: "GET", path: "/tenants/:externalId/batch/:batchId" },
   usage: { method: "GET", path: "/usage" },
+  balance: { method: "GET", path: "/balance" },
+  balanceMovements: { method: "GET", path: "/balance/movements" },
+  topup: { method: "POST", path: "/topup" },
   getWebhook: { method: "GET", path: "/webhook" },
   setWebhook: { method: "PUT", path: "/webhook" },
   testWebhook: { method: "POST", path: "/webhook/test" },
@@ -772,6 +818,14 @@ var PARTNER_ADMIN_ROUTES = {
   setFallbackZone: { method: "PUT", path: "/api/partners/:partnerId/fallback-zone" },
   /** La zona de respaldo y si la delegación ya se ve en el DNS público. */
   getFallbackZone: { method: "GET", path: "/api/partners/:partnerId/fallback-zone" },
+  /** El saldo del partner (dueño o MailMask). */
+  getBalance: { method: "GET", path: "/api/partners/:partnerId/balance" },
+  /** Sólo MailMask (admin): abono o cargo manual (`adjust`). */
+  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" },
+  /** 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" },
   createCredential: { method: "POST", path: "/api/partners/:partnerId/credentials" },
   rotateCredential: { method: "POST", path: "/api/partners/:partnerId/credentials/:keyId/rotate" },
@@ -785,8 +839,8 @@ var PartnerApiError = class extends MailMaskError {
       code: body.code,
       requestId: meta.requestId,
       cause: meta.cause,
-      // `quota_exceeded` es un 429 que no se arregla reintentando: hasta el mes siguiente.
-      retryable: status === 0 || status >= 500 || status === 429 && body.code !== "quota_exceeded"
+      // `daily_limit` (y el viejo `quota_exceeded`) son 429 que no se arreglan reintentando: hasta mañana.
+      retryable: status === 0 || status >= 500 || status === 429 && body.code !== "quota_exceeded" && body.code !== "daily_limit"
     });
     this.kind = "unknown";
     this.name = "PartnerApiError";
@@ -889,6 +943,29 @@ var RateLimitError = class extends QuotaError {
     this.kind = "rate_limit";
   }
 };
+var DailyLimitError = class extends QuotaError {
+  constructor() {
+    super(...arguments);
+    this.name = "DailyLimitError";
+    this.kind = "daily_limit";
+  }
+  get sentToday() {
+    return this.body.sentToday;
+  }
+};
+var InsufficientBalanceError = class extends PartnerApiError {
+  constructor() {
+    super(...arguments);
+    this.name = "InsufficientBalanceError";
+    this.kind = "insufficient_balance";
+  }
+  get balanceCents() {
+    return this.body.balanceCents;
+  }
+  get requiredCents() {
+    return this.body.requiredCents;
+  }
+};
 var NetworkError = class extends PartnerApiError {
   constructor(message, cause) {
     super(0, message, {}, { cause });
@@ -907,10 +984,13 @@ function errorFor(status, body, fallback, meta = {}) {
   const msg = body.error || fallback;
   if (body.code === "reputation_hold") return new ReputationHoldError(status, msg, body, meta);
   if (body.code === "recipient_suppressed") return new RecipientSuppressedError(status, msg, body, meta);
+  if (status === 429 && body.code === "daily_limit") return new DailyLimitError(status, msg, body, meta);
   if (status === 429 && body.code !== "quota_exceeded") return new RateLimitError(status, msg, body, meta);
   switch (status) {
     case 401:
       return new AuthError(status, msg, body, meta);
+    case 402:
+      return new InsufficientBalanceError(status, msg, body, meta);
     case 403:
       return new ForbiddenError(status, msg, body, meta);
     case 404:
@@ -1111,6 +1191,26 @@ var MailMaskPartner = class {
   async batchStatus(externalId, batchId) {
     return (await this.request("GET", routePath(PARTNER_ROUTES.getBatch.path, { externalId, batchId }))).data;
   }
+  /** Saldo prepagado: saldo, precios, última recarga y consumo del mes (centavos MXN). */
+  async balance() {
+    return (await this.request("GET", PARTNER_ROUTES.balance.path)).data;
+  }
+  /** Movimientos del saldo, del más nuevo al más viejo; pagina con `nextCursor`. */
+  async balanceMovements(query = {}) {
+    const q = new URLSearchParams();
+    if (query.cursor) q.set("cursor", query.cursor);
+    if (query.limit !== void 0) q.set("limit", String(query.limit));
+    if (query.kind?.length) q.set("kind", query.kind.join(","));
+    const qs = q.toString();
+    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.
+   */
+  async topup(input) {
+    return (await this.request("POST", PARTNER_ROUTES.topup.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)}` : "";
@@ -1315,6 +1415,10 @@ var MailMaskPartnerAdmin = class {
   resumeTenant(partnerId, externalId) {
     return this.req("resumeTenant", { partnerId, externalId });
   }
+  /** Sólo MailMask: tope diario fijo del tenant, o `null` para volver al calentamiento. */
+  setTenantDailyLimit(partnerId, externalId, limit) {
+    return this.req("setTenantDailyLimit", { partnerId, externalId }, { limit });
+  }
   /**
    * Sólo MailMask (admin): crea o adopta la hosted zone de la zona de respaldo (`marketing.denik.me`)
    * y devuelve los NS que el partner tiene que delegar. Idempotente con la misma zona.
@@ -1326,6 +1430,18 @@ var MailMaskPartnerAdmin = class {
   getFallbackZone(partnerId) {
     return this.req("getFallbackZone", { partnerId });
   }
+  /** Saldo del partner con sus últimos 20 movimientos (dueño o MailMask). */
+  getBalance(partnerId) {
+    return this.req("getBalance", { partnerId });
+  }
+  /** Sólo MailMask (admin): abono (o cargo, negativo) manual. Con la misma `idempotencyKey` no se repite. */
+  adjustBalance(partnerId, input) {
+    return this.req("adjustBalance", { partnerId }, input);
+  }
+  /** Liga de MercadoPago para recargar, con la llave del dueño. */
+  topup(partnerId, input) {
+    return this.req("topup", { partnerId }, input);
+  }
   listCredentials(partnerId) {
     return this.req("listCredentials", { partnerId });
   }
@@ -1344,11 +1460,15 @@ var MailMaskPartnerAdmin = class {
 };
 export {
   AuthError,
+  BALANCE_LOW_FRACTION,
+  BALANCE_MOVEMENT_KINDS,
   ConflictError,
   DOMAIN_CLAIM_TTL_DAYS,
+  DailyLimitError,
   EXTERNAL_ID_RE,
   FALLBACK_LABEL_RE,
   ForbiddenError,
+  InsufficientBalanceError,
   MAX_BATCH_RECIPIENTS,
   MAX_TAGS,
   MAX_TEMPLATE_VARS,
@@ -1365,9 +1485,14 @@ export {
   PARTNER_API_PREFIX,
   PARTNER_ERROR_STATUS,
   PARTNER_HEADERS,
+  PARTNER_PRICE_PER_EMAIL_CENTS,
   PARTNER_ROUTES,
   PARTNER_SIGNATURE_TOLERANCE_S,
+  PARTNER_TENANT_MONTH_CENTS,
+  PARTNER_TOPUP_MAX_CENTS,
+  PARTNER_TOPUP_MIN_CENTS,
   PARTNER_WEBHOOK_EVENTS,
+  PARTNER_WELCOME_CENTS,
   PartnerApiError,
   PausedError,
   QuotaError,
@@ -1378,12 +1503,16 @@ export {
   STRICT_FIRST_DAYS,
   TAG_RE,
   TEMPLATE_VAR_NAME_RE,
+  TENANT_DAILY_LIMIT_MAX,
+  TENANT_DAILY_LIMIT_START,
+  TENANT_WARMUP_STEP_DAYS,
   TimeoutError,
   UNSUBSCRIBE_URL_VAR,
   ValidationError,
   WEBHOOK_HEADERS,
   WEBHOOK_TOLERANCE_MS,
   createWebhookHandler,
+  estimateSendDays,
   isValidExternalId,
   isValidFallbackLabel,
   partnerSignatureBase,
@@ -1396,5 +1525,6 @@ export {
   templateVarsProblem,
   verifyWebhook,
   verifyWebhookSignature,
+  warmupLimit,
   webhookSignatureBase
 };

package/dist/partner-contract.d.ts

@@ -59,7 +59,17 @@ export declare const PARTNER_ERROR_STATUS: {
     readonly recipient_suppressed: 422;
     /** El tenant está en pausa (por MailMask o por el partner). No se manda nada hasta `resume`. */
     readonly tenant_paused: 423;
-    /** Cuota mensual del tenant agotada. */
+    /**
+     * Saldo prepagado insuficiente (con `balanceCents` y `requiredCents`). No se reintenta: recarga
+     * con `POST /topup`.
+     */
+    readonly insufficient_balance: 402;
+    /**
+     * El tenant llegó a su límite del día (con `limit`, `sentToday` y `resetsAt`, la medianoche UTC).
+     * Sólo en envíos sueltos: un lote no falla, espera al día siguiente (`batch.throttled`).
+     */
+    readonly daily_limit: 429;
+    /** Ya no sale desde la 0.8 (no hay tope mensual); se deja para clientes viejos. */
     readonly quota_exceeded: 429;
     /** Demasiadas peticiones; reintenta tras `Retry-After`. */
     readonly rate_limited: 429;
@@ -72,9 +82,13 @@ export interface PartnerErrorBody {
     code: PartnerErrorCode;
     /** Sólo en `invalid_request`: el campo que falló, si aplica. */
     field?: string;
-    /** Sólo en `quota_exceeded`: el tope del mes y cuándo se reinicia (ISO, día 1 a las 00:00 UTC). */
+    /** Sólo en `daily_limit`: el límite de hoy, lo enviado y cuándo se reinicia (medianoche UTC). */
     limit?: number;
+    sentToday?: number;
     resetsAt?: string;
+    /** Sólo en `insufficient_balance`: saldo actual y lo que pedía el envío (centavos MXN). */
+    balanceCents?: number;
+    requiredCents?: number;
     /** Sólo en `recipient_suppressed`. */
     reason?: SuppressionReason;
     stream?: MessageStream;
@@ -104,7 +118,38 @@ export interface Tenant {
     lastSendAt: string | null;
     createdAt: string;
     updatedAt: string;
+    /** Límite diario con calentamiento. Ver `TenantSending`. */
+    sending: TenantSending;
 }
+/**
+ * Límite diario por tenant que crece solo, como el calentamiento de SES: empieza en
+ * `TENANT_DAILY_LIMIT_START` al primer envío y se duplica cada `TENANT_WARMUP_STEP_DAYS` días sanos
+ * (rebotes < 2 %, quejas < 0.1 %) hasta `TENANT_DAILY_LIMIT_MAX`. Una pausa por reputación lo
+ * 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_WARMUP_STEP_DAYS = 7;
+/** El límite del escalón `step` (0 = inicio). */
+export declare function warmupLimit(step: number): number;
+export interface TenantSending {
+    /** Correos que puede mandar hoy (UTC) en total. */
+    dailyLimit: number;
+    sentToday: number;
+    /** Medianoche UTC siguiente. */
+    resetsAt: string;
+    /** Cuándo sube al siguiente escalón si sigue sano; null = ya en el máximo, con tope fijo o sin envíos aún. */
+    nextStepAt: string | null;
+    /** El límite que tendrá en `nextStepAt`; null si no sube. */
+    nextStepLimit: number | null;
+    /** true = MailMask fijó el límite a mano (no se calienta). */
+    fixed: boolean;
+}
+/**
+ * Días (contando hoy) que tarda en salir un lote de `recipients` correos si los escalones llegan a
+ * tiempo. 1 = sale hoy. Sirve para avisar «se manda en N días» antes de encolar.
+ */
+export declare function estimateSendDays(s: TenantSending, recipients: number): number;
 /** `PUT /tenants/:externalId` — crea o actualiza. 201 si lo creó, 200 si ya existía. */
 export interface PutTenantRequest {
     name?: string;
@@ -343,6 +388,11 @@ export interface BatchStatus {
     lastError: string | null;
     createdAt: string;
     completedAt: string | null;
+    /**
+     * El lote llegó al límite diario del tenant y sigue solo a esta hora (medianoche UTC); null si no
+     * está esperando por el límite. Mientras espera, el lote no caduca.
+     */
+    waitingUntil: string | null;
     /**
      * Sólo en modo de prueba: el lote se valida y responde `completed` al instante (los suprimidos en
      * `skippedSuppressed`, el resto en `sent`), con `batchId` `test_…` que no se guarda (su GET da 404).
@@ -360,6 +410,8 @@ export interface TenantUsage {
     bounced: number;
     complained: number;
     unsubscribed: number;
+    /** Límite diario de hoy; falta si el tenant ya se borró. */
+    sending?: TenantSending;
 }
 /** `GET /usage?month=YYYY-MM` (default: el mes en curso, UTC). Activo = al menos un envío en el mes. */
 export interface UsageResponse {
@@ -368,6 +420,120 @@ export interface UsageResponse {
     sent: number;
     tenants: TenantUsage[];
 }
+/**
+ * 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.
+ */
+/** 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;
+/** `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";
+export declare const BALANCE_MOVEMENT_KINDS: readonly BalanceMovementKind[];
+export interface BalanceMovement {
+    id: number;
+    kind: BalanceMovementKind;
+    /** Positivo = abono (recarga, devolución, ajuste a favor); negativo = cargo. */
+    amountCents: number;
+    balanceAfterCents: number;
+    /** Tenant del cargo (`send`, `tenant_fee`, `refund`); null en recargas y ajustes. */
+    externalId: string | null;
+    /** Referencia: `batch:<id>`, mes de la cuota (`YYYY-MM`), pago de MercadoPago… */
+    ref: string | null;
+    note: string | null;
+    createdAt: string;
+}
+/** `GET /balance` */
+export interface BalanceResponse {
+    currency: "MXN";
+    /** 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;
+    };
+    lastTopup: {
+        amountCents: number;
+        at: string;
+    } | null;
+    /** Debajo de esto sale `balance.low`; null sin recargas. */
+    lowBalanceThresholdCents: number | null;
+    /** Mes en curso (UTC). */
+    month: string;
+    /** Tenants que enviaron este mes (la misma cuenta que `/usage`): cada uno paga la cuota del mes. */
+    activeTenants: number;
+    /** Correos cobrados en el mes (sin los devueltos). */
+    monthEmails: number;
+    /** Lo gastado en el mes: correos + cuotas − devoluciones. */
+    monthSpentCents: number;
+}
+/** `GET /balance/movements?cursor=&limit=&kind=topup,adjust` — del más nuevo al más viejo. */
+export interface BalanceMovementsQuery {
+    cursor?: string;
+    /** 1–200, default 50. */
+    limit?: number;
+    kind?: BalanceMovementKind[];
+}
+export interface BalanceMovementsResponse {
+    movements: BalanceMovement[];
+    nextCursor: string | null;
+}
+/**
+ * `POST /topup` — liga de pago único de MercadoPago. El saldo sube cuando MercadoPago confirma
+ * 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;
+    returnUrl?: string;
+}
+export interface TopupResponse {
+    topupId: string;
+    amountCents: number;
+    /** Abre esto en el navegador de quien paga. */
+    initPoint: string;
+}
+/**
+ * `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).
+ */
+/** Un tenant en la ficha: los 50 que enviaron más recientemente, con su límite de hoy. */
+export interface PartnerDetailTenant {
+    externalId: string;
+    name: string | null;
+    status: TenantStatus;
+    lastSendAt: string | null;
+    sending: TenantSending;
+}
+export type PartnerBalanceDetail = BalanceResponse & {
+    movements: BalanceMovement[];
+    partner: PartnerSummary;
+    tenants: PartnerDetailTenant[];
+    staff: boolean;
+};
+/** `PUT /api/partners/:partnerId/tenants/:externalId/daily-limit` — sólo MailMask: tope fijo o `null` (vuelve al calentamiento). */
+export interface SetTenantDailyLimitRequest {
+    limit: number | null;
+}
+/** `POST /api/partners/:partnerId/balance/adjust` — sólo MailMask (admin): abono o cargo manual. */
+export interface AdjustBalanceRequest {
+    /** Centavos MXN, distinto de 0 (negativo = cargo). */
+    amountCents: number;
+    note: string;
+    /** Repetir con la misma llave no vuelve a abonar. */
+    idempotencyKey?: string;
+}
 /** `GET /webhook` */
 export interface WebhookConfig {
     url: string | null;
@@ -401,7 +567,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"];
+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 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: {
@@ -479,9 +645,23 @@ export interface PartnerEventData {
         domain: string;
         mailFromVerified: boolean;
     };
+    /** El saldo prepagado bajó del 20 % de la última recarga. `externalId` va null. */
+    "balance.low": {
+        balanceCents: number;
+        thresholdCents: number;
+        lastTopupCents: number;
+    };
+    /** Un lote llegó al límite diario del tenant: sigue solo en `resumesAt`. Una vez por lote. */
+    "batch.throttled": {
+        batchId: string;
+        sent: number;
+        total: number;
+        dailyLimit: number;
+        resumesAt: string;
+    };
     ping: Record<string, never>;
 }
-/** Sobre de cada evento. `externalId` es null sólo en `ping`. */
+/** Sobre de cada evento. `externalId` es null en `ping` y `balance.low`. */
 export interface PartnerWebhookPayload<E extends keyof PartnerEventData = keyof PartnerEventData> {
     /** Id de la entrega (igual que `X-MailMask-Delivery`); úsalo para descartar duplicados. */
     id: string;
@@ -498,10 +678,11 @@ export interface PartnerWebhookPayload<E extends keyof PartnerEventData = keyof
 export type ReputationPolicy = "standard" | "strict";
 /** Primer mes del partner: sus tenants van en Strict salvo que MailMask fije otra política. */
 export declare const STRICT_FIRST_DAYS = 30;
-/** `GET /api/partners` — los partners de la cuenta. */
+/** `GET /api/partners` — los partners de la cuenta. MailMask (admin) con `?all=1`: todos, con `tenants`. */
 export interface PartnerSummary {
     id: string;
     name: string;
+    /** `sendsPerTenantMonth` ya no frena (0.8): el límite es diario por tenant, ver `TenantSending`. */
     plan: {
         includedTenants: number;
         sendsPerTenantMonth: number;
@@ -515,6 +696,15 @@ 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`. */
+    balanceCents: number;
+    /** Sólo en `GET /api/partners?all=1` (MailMask, admin): tenants totales y activos del mes. */
+    tenants?: {
+        total: number;
+        activeThisMonth: number;
+    };
+    /** Sólo en `?all=1` (admin): cuenta dueña. */
+    ownerEmail?: string;
 }
 /** `POST /api/partners` — alta (sólo MailMask, admin). 201 con `PartnerSummary`. */
 export interface CreatePartnerRequest {
@@ -630,6 +820,18 @@ export declare const PARTNER_ROUTES: {
         readonly method: "GET";
         readonly path: "/usage";
     };
+    readonly balance: {
+        readonly method: "GET";
+        readonly path: "/balance";
+    };
+    readonly balanceMovements: {
+        readonly method: "GET";
+        readonly path: "/balance/movements";
+    };
+    readonly topup: {
+        readonly method: "POST";
+        readonly path: "/topup";
+    };
     readonly getWebhook: {
         readonly method: "GET";
         readonly path: "/webhook";
@@ -676,6 +878,26 @@ export declare const PARTNER_ADMIN_ROUTES: {
         readonly method: "GET";
         readonly path: "/api/partners/:partnerId/fallback-zone";
     };
+    /** El saldo del partner (dueño o MailMask). */
+    readonly getBalance: {
+        readonly method: "GET";
+        readonly path: "/api/partners/:partnerId/balance";
+    };
+    /** Sólo MailMask (admin): abono o cargo manual (`adjust`). */
+    readonly adjustBalance: {
+        readonly method: "POST";
+        readonly path: "/api/partners/:partnerId/balance/adjust";
+    };
+    /** Recarga con MercadoPago desde la sesión del dueño (misma respuesta que `POST /topup`). */
+    readonly topup: {
+        readonly method: "POST";
+        readonly path: "/api/partners/:partnerId/topup";
+    };
+    /** Sólo MailMask: fija (o quita, con `null`) el límite diario de un tenant. Devuelve el `Tenant`. */
+    readonly setTenantDailyLimit: {
+        readonly method: "PUT";
+        readonly path: "/api/partners/:partnerId/tenants/:externalId/daily-limit";
+    };
     readonly listCredentials: {
         readonly method: "GET";
         readonly path: "/api/partners/:partnerId/credentials";

package/dist/partner.d.ts

@@ -1,12 +1,12 @@
 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 } 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 } from "./partner-contract.js";
 export * from "./partner-contract.js";
 /**
  * Discriminante estable de los errores de partners, para un `switch` sin cadenas de `instanceof`.
  * `network` y `timeout` llevan `status` 0 (no hubo respuesta); `unknown` es un status que el
  * contrato no define (p. ej. un 400 de un proxy).
  */
-export type PartnerErrorKind = "auth" | "forbidden" | "reputation_hold" | "not_found" | "conflict" | "validation" | "suppressed" | "paused" | "quota" | "rate_limit" | "server" | "network" | "timeout" | "unknown";
+export type PartnerErrorKind = "auth" | "forbidden" | "reputation_hold" | "not_found" | "conflict" | "validation" | "suppressed" | "paused" | "quota" | "daily_limit" | "insufficient_balance" | "rate_limit" | "server" | "network" | "timeout" | "unknown";
 /** Metadatos de la respuesta que no vienen en el cuerpo. */
 export interface PartnerErrorMeta {
     requestId?: string;
@@ -100,6 +100,25 @@ export declare class RateLimitError extends QuotaError {
     name: string;
     kind: PartnerErrorKind;
 }
+/**
+ * 429 `daily_limit`: el tenant llegó a su límite del día (crece solo con buena reputación). NO se
+ * reintenta: vuelve a intentar después de `resetsAt` (medianoche UTC) o manda un `batch`, que espera
+ * solo. Trae `limit` y `sentToday`.
+ */
+export declare class DailyLimitError extends QuotaError {
+    name: string;
+    kind: PartnerErrorKind;
+    get sentToday(): number | undefined;
+}
+/**
+ * 402 `insufficient_balance`: el saldo prepagado no alcanza. No se reintenta: recarga con `partner.topup()`. Trae `balanceCents` y `requiredCents`.
+ */
+export declare class InsufficientBalanceError extends PartnerApiError {
+    name: string;
+    kind: PartnerErrorKind;
+    get balanceCents(): number | undefined;
+    get requiredCents(): number | undefined;
+}
 /** No hubo respuesta: DNS, conexión rechazada o cortada. `status` 0. */
 export declare class NetworkError extends PartnerApiError {
     name: string;
@@ -218,6 +237,15 @@ export declare class MailMaskPartner {
     }>;
     /** Estado de un lote (`batchId` del resultado de `batch`): envíos y, después, entregas, rebotes, quejas y bajas. */
     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.
+     */
+    topup(input: TopupRequest): Promise<TopupResponse>;
     /** Uso del mes (`YYYY-MM`, default el mes en curso UTC): tenants activos y envíos. */
     usage(opts?: {
         month?: string;
@@ -354,6 +382,8 @@ export declare class MailMaskPartnerAdmin {
     setReputationPolicy(partnerId: string, policy: ReputationPolicy | null): 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. */
+    setTenantDailyLimit(partnerId: string, externalId: string, limit: number | null): Promise<Tenant>;
     /**
      * Sólo MailMask (admin): crea o adopta la hosted zone de la zona de respaldo (`marketing.denik.me`)
      * y devuelve los NS que el partner tiene que delegar. Idempotente con la misma zona.
@@ -361,6 +391,12 @@ export declare class MailMaskPartnerAdmin {
     setFallbackZone(partnerId: string, zone: string): Promise<FallbackZone>;
     /** La zona de respaldo y si el DNS público ya ve la delegación. */
     getFallbackZone(partnerId: string): Promise<FallbackZone>;
+    /** Saldo del partner con sus últimos 20 movimientos (dueño o MailMask). */
+    getBalance(partnerId: string): Promise<PartnerBalanceDetail>;
+    /** Sólo MailMask (admin): abono (o cargo, negativo) manual. Con la misma `idempotencyKey` no se repite. */
+    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>;
     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.6.1",
+  "version": "0.8.0",
   "description": "Official SDK for the MailMask email alias/forwarding API",
   "type": "module",
   "main": "./dist/index.cjs",