@easybits.cloud/mailmask 0.6.1 → 0.7.0

package/dist/index.cjs

@@ -21,11 +21,14 @@ 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,
   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,8 +45,12 @@ __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,
   PartnerApiError: () => PartnerApiError,
   PausedError: () => PausedError,
@@ -716,6 +723,11 @@ 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,
+  /**
+   * Saldo prepagado insuficiente (con `balanceCents` y `requiredCents`). Sólo cuando MailMask
+   * activó el cobro por adelantado del partner. No se reintenta: recarga con `POST /topup`.
+   */
+  insufficient_balance: 402,
   /** Cuota mensual del tenant agotada. */
   quota_exceeded: 429,
   /** Demasiadas peticiones; reintenta tras `Retry-After`. */
@@ -795,6 +807,12 @@ 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_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 +822,8 @@ var PARTNER_WEBHOOK_EVENTS = [
   "contact.unsubscribed",
   "tenant.paused",
   "tenant.resumed",
-  "domain.verified"
+  "domain.verified",
+  "balance.low"
 ];
 var WEBHOOK_HEADERS = {
   event: "X-MailMask-Event",
@@ -836,6 +855,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 +873,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" },
+  /** Sólo MailMask (admin): prende o apaga el cobro por adelantado. */
+  setPrepaidEnforced: { method: "PUT", path: "/api/partners/:partnerId/prepaid" },
+  /** Recarga con MercadoPago desde la sesión del dueño (misma respuesta que `POST /topup`). */
+  topup: { method: "POST", path: "/api/partners/:partnerId/topup" },
   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" },
@@ -968,6 +998,19 @@ var RateLimitError = class extends QuotaError {
     this.kind = "rate_limit";
   }
 };
+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 });
@@ -990,6 +1033,8 @@ function errorFor(status, body, fallback, 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 +1235,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)}` : "";
@@ -1405,6 +1470,22 @@ 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);
+  }
+  /** Sólo MailMask (admin): prende o apaga el cobro por adelantado del partner. */
+  setPrepaidEnforced(partnerId, enforced) {
+    return this.req("setPrepaidEnforced", { partnerId }, { enforced });
+  }
+  /** 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 +1505,14 @@ 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,
   EXTERNAL_ID_RE,
   FALLBACK_LABEL_RE,
   ForbiddenError,
+  InsufficientBalanceError,
   MAX_BATCH_RECIPIENTS,
   MAX_TAGS,
   MAX_TEMPLATE_VARS,
@@ -1445,8 +1529,12 @@ 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,
   PartnerApiError,
   PausedError,

package/dist/index.js

@@ -637,6 +637,11 @@ 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,
+  /**
+   * Saldo prepagado insuficiente (con `balanceCents` y `requiredCents`). Sólo cuando MailMask
+   * activó el cobro por adelantado del partner. No se reintenta: recarga con `POST /topup`.
+   */
+  insufficient_balance: 402,
   /** Cuota mensual del tenant agotada. */
   quota_exceeded: 429,
   /** Demasiadas peticiones; reintenta tras `Retry-After`. */
@@ -716,6 +721,12 @@ 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_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 +736,8 @@ var PARTNER_WEBHOOK_EVENTS = [
   "contact.unsubscribed",
   "tenant.paused",
   "tenant.resumed",
-  "domain.verified"
+  "domain.verified",
+  "balance.low"
 ];
 var WEBHOOK_HEADERS = {
   event: "X-MailMask-Event",
@@ -757,6 +769,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 +787,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" },
+  /** Sólo MailMask (admin): prende o apaga el cobro por adelantado. */
+  setPrepaidEnforced: { method: "PUT", path: "/api/partners/:partnerId/prepaid" },
+  /** Recarga con MercadoPago desde la sesión del dueño (misma respuesta que `POST /topup`). */
+  topup: { method: "POST", path: "/api/partners/:partnerId/topup" },
   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" },
@@ -889,6 +912,19 @@ var RateLimitError = class extends QuotaError {
     this.kind = "rate_limit";
   }
 };
+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 });
@@ -911,6 +947,8 @@ function errorFor(status, body, fallback, 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 +1149,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)}` : "";
@@ -1326,6 +1384,22 @@ 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);
+  }
+  /** Sólo MailMask (admin): prende o apaga el cobro por adelantado del partner. */
+  setPrepaidEnforced(partnerId, enforced) {
+    return this.req("setPrepaidEnforced", { partnerId }, { enforced });
+  }
+  /** 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 +1418,14 @@ var MailMaskPartnerAdmin = class {
 };
 export {
   AuthError,
+  BALANCE_LOW_FRACTION,
+  BALANCE_MOVEMENT_KINDS,
   ConflictError,
   DOMAIN_CLAIM_TTL_DAYS,
   EXTERNAL_ID_RE,
   FALLBACK_LABEL_RE,
   ForbiddenError,
+  InsufficientBalanceError,
   MAX_BATCH_RECIPIENTS,
   MAX_TAGS,
   MAX_TEMPLATE_VARS,
@@ -1365,8 +1442,12 @@ 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,
   PartnerApiError,
   PausedError,

package/dist/partner-contract.d.ts

@@ -59,6 +59,11 @@ 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;
+    /**
+     * Saldo prepagado insuficiente (con `balanceCents` y `requiredCents`). Sólo cuando MailMask
+     * activó el cobro por adelantado del partner. No se reintenta: recarga con `POST /topup`.
+     */
+    readonly insufficient_balance: 402;
     /** Cuota mensual del tenant agotada. */
     readonly quota_exceeded: 429;
     /** Demasiadas peticiones; reintenta tras `Retry-After`. */
@@ -75,6 +80,9 @@ export interface PartnerErrorBody {
     /** Sólo en `quota_exceeded`: el tope del mes y cuándo se reinicia (ISO, día 1 a las 00:00 UTC). */
     limit?: 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;
@@ -368,6 +376,113 @@ 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;
+/** 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";
+    balanceCents: number;
+    /**
+     * true = sin saldo suficiente los envíos se rechazan (402 `insufficient_balance`) y los lotes
+     * esperan. false = el saldo se lleva igual (puede quedar negativo) pero no frena nada.
+     */
+    enforced: boolean;
+    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 a los que ya se les cobró 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).
+ */
+export type PartnerBalanceDetail = BalanceResponse & {
+    movements: BalanceMovement[];
+    partner: PartnerSummary;
+    staff: boolean;
+};
+/** `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;
+}
+/** `PUT /api/partners/:partnerId/prepaid` — sólo MailMask (admin): prende o apaga el cobro por adelantado. */
+export interface SetPrepaidEnforcedRequest {
+    enforced: boolean;
+}
 /** `GET /webhook` */
 export interface WebhookConfig {
     url: string | null;
@@ -401,7 +516,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"];
 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 +594,15 @@ 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;
+    };
     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,7 +619,7 @@ 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;
@@ -515,6 +636,16 @@ export interface PartnerSummary {
     effectiveReputationPolicy: ReputationPolicy;
     /** Zona de respaldo (`marketing.denik.me`); null = sin zona. Ver `FallbackZone`. */
     fallbackZone: string | null;
+    /** Saldo prepagado (centavos MXN) y si ya frena envíos. Ver `BalanceResponse`. */
+    balanceCents: number;
+    prepaidEnforced: boolean;
+    /** 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 +761,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 +819,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";
+    };
+    /** Sólo MailMask (admin): prende o apaga el cobro por adelantado. */
+    readonly setPrepaidEnforced: {
+        readonly method: "PUT";
+        readonly path: "/api/partners/:partnerId/prepaid";
+    };
+    /** 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";
+    };
     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" | "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,16 @@ export declare class RateLimitError extends QuotaError {
     name: string;
     kind: PartnerErrorKind;
 }
+/**
+ * 402 `insufficient_balance`: el saldo prepagado no alcanza (sólo con el cobro por adelantado
+ * prendido). 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 +228,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;
@@ -361,6 +380,14 @@ 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>;
+    /** Sólo MailMask (admin): prende o apaga el cobro por adelantado del partner. */
+    setPrepaidEnforced(partnerId: string, enforced: boolean): Promise<PartnerSummary>;
+    /** 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.7.0",
   "description": "Official SDK for the MailMask email alias/forwarding API",
   "type": "module",
   "main": "./dist/index.cjs",