@easybits.cloud/mailmask 0.4.12 → 0.7.0

package/dist/partner-contract.d.ts

@@ -0,0 +1,858 @@
+/** Prefijo de la API. Todas las rutas de partner cuelgan de aquí. */
+export declare const PARTNER_API_PREFIX = "/api/partner/v1";
+/** Headers que manda el servidor del partner en CADA petición. */
+export declare const PARTNER_HEADERS: {
+    /** Id público de la credencial: `mmk_…`. */
+    readonly key: "X-MailMask-Key";
+    /** Segundos Unix (no milisegundos) del momento de firmar. */
+    readonly ts: "X-MailMask-Ts";
+    /** HMAC-SHA256 en hex minúsculas (64 caracteres), sin prefijo. */
+    readonly sig: "X-MailMask-Sig";
+    /** Opcional en `send`/`batch`: mismo efecto que `idempotencyKey` en el cuerpo. */
+    readonly idempotencyKey: "Idempotency-Key";
+    /**
+     * Opcional en `send`/`batch`: `1` = modo de prueba. Valida todo igual (firma, tenant, dominio,
+     * cuerpo, variables, supresión, cuota) y responde como de verdad con `test: true`, pero no envía
+     * a SES, no consume cuota, no cuenta como tenant activo y no emite eventos al webhook. En las
+     * demás rutas se ignora.
+     */
+    readonly test: "X-MailMask-Test";
+};
+/** Ventana de la firma: el servidor rechaza un `ts` a más de 300 s de su reloj. */
+export declare const PARTNER_SIGNATURE_TOLERANCE_S = 300;
+/**
+ * Texto canónico que se firma con HMAC-SHA256 usando el secreto `mms_…` como llave:
+ *
+ *     `${ts}.${keyId}.${METHOD}.${pathAndQuery}.${rawBody}`
+ *
+ * - `ts`: los mismos segundos que van en `X-MailMask-Ts`.
+ * - `METHOD`: en mayúsculas (`GET`, `PUT`, `POST`, `DELETE`).
+ * - `pathAndQuery`: la ruta tal como viaja, con su query (`/api/partner/v1/usage?month=2026-10`),
+ *   sin esquema ni host.
+ * - `rawBody`: el cuerpo exacto en bytes UTF-8; cadena vacía si no hay cuerpo (GET, DELETE).
+ *
+ * El método y la ruta van dentro de la firma (el plan de gs firmaba sólo el cuerpo): sin ellos,
+ * un GET firmado —cuerpo vacío— se podría repetir contra CUALQUIER otra ruta de lectura durante
+ * los 300 s de la ventana.
+ */
+export declare function partnerSignatureBase(ts: string | number, keyId: string, method: string, pathAndQuery: string, rawBody: string): string;
+/**
+ * Todo error responde JSON `{ error, code }` con el status de la tabla. `error` es texto en
+ * español para una persona; los programas deciden por `code` (y por el status).
+ */
+export declare const PARTNER_ERROR_STATUS: {
+    /** Firma ausente, mala, vencida, de una credencial revocada o inexistente: SIEMPRE el mismo 401. */
+    readonly unauthorized: 401;
+    /** Firma válida, pero el partner está desactivado o el tenant suspendido por MailMask. */
+    readonly forbidden: 403;
+    /** `resume` de una pausa que puso MailMask o SES por reputación: sólo MailMask la levanta. */
+    readonly reputation_hold: 403;
+    /** El tenant, dominio, lote o recurso no existe PARA ESTE partner (los de otros también dan 404). */
+    readonly not_found: 404;
+    /** El dominio ya es de otra cuenta o de otro tenant; máximo de credenciales; estado incompatible. */
+    readonly conflict: 409;
+    /** Validación: campos faltantes o inválidos, remitente fuera de los dominios del tenant,
+     * dominio sin verificar. */
+    readonly invalid_request: 422;
+    /** El destinatario está suprimido para este stream (con `reason`, `stream` y `recipient`). No es
+     * un error del cuerpo: no reintentes ni cambies el código, marca a la persona en tu sistema. */
+    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`. */
+    readonly rate_limited: 429;
+    /** Falla nuestra o de SES; reintentable con la misma `idempotencyKey`. */
+    readonly internal: 500;
+};
+export type PartnerErrorCode = keyof typeof PARTNER_ERROR_STATUS;
+export interface PartnerErrorBody {
+    error: string;
+    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). */
+    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;
+    recipient?: string;
+}
+/** `externalId`: el id del cliente en la app del partner. 1–128, empieza con letra o número. */
+export declare const EXTERNAL_ID_RE: RegExp;
+export declare function isValidExternalId(id: string): boolean;
+/** Máximo de destinatarios por lote. */
+export declare const MAX_BATCH_RECIPIENTS = 10000;
+/** Máximo de etiquetas por envío; llave y valor `[A-Za-z0-9_-]{1,64}` (es lo que acepta SES). */
+export declare const MAX_TAGS = 10;
+export declare const TAG_RE: RegExp;
+export type TenantStatus = "active" | "paused" | "suspended";
+/** Quién puso la pausa. Sólo una pausa `partner` la levanta el partner. */
+export type PausedBy = "partner" | "mailmask" | "ses";
+export interface Tenant {
+    externalId: string;
+    name: string | null;
+    /** `paused`: lo pausó la pausa automática o el partner (423 al enviar). `suspended`: MailMask (403). */
+    status: TenantStatus;
+    pausedReason: string | null;
+    /** null si no está en pausa. */
+    pausedBy: PausedBy | null;
+    /** Dominios del tenant, en minúsculas. */
+    domains: string[];
+    lastSendAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/** `PUT /tenants/:externalId` — crea o actualiza. 201 si lo creó, 200 si ya existía. */
+export interface PutTenantRequest {
+    name?: string;
+}
+export type PutTenantResponse = Tenant;
+/** `GET /tenants?status=&limit=&cursor=` — orden por `createdAt`, `limit` 1–200 (default 50). */
+export interface ListTenantsQuery {
+    status?: TenantStatus;
+    limit?: number;
+    cursor?: string;
+}
+export interface ListTenantsResponse {
+    tenants: Tenant[];
+    /** null = no hay más. */
+    nextCursor: string | null;
+}
+/** `GET /tenants/:externalId` */
+export type GetTenantResponse = Tenant;
+/**
+ * `DELETE /tenants/:externalId` — borra el tenant y suelta sus dominios (los que nadie más usa se
+ * borran con sus recursos en SES). 409 si está en pausa por reputación (`mailmask` o `ses`). Los
+ * números de la pausa (ventana de 7 días) son por partner y dominio: recrear el tenant no los borra.
+ */
+export interface DeleteTenantResponse {
+    ok: true;
+    removedDomains: string[];
+}
+/** `POST /tenants/:externalId/pause` */
+export interface PauseTenantRequest {
+    reason?: string;
+}
+/**
+ * `POST /tenants/:externalId/pause` y `/resume` devuelven el tenant ya cambiado. `resume` sólo
+ * levanta pausas `partner`; las de `mailmask` o `ses` dan 403 `reputation_hold`.
+ */
+export type PauseTenantResponse = Tenant;
+export type ResumeTenantResponse = Tenant;
+export interface PartnerDnsRecord {
+    /** `claim`, `mx`, `verification`, `dkim1..3`, `spf`, `dmarc`, `mailfrom-mx`, `mailfrom-spf`. */
+    id: string;
+    type: "MX" | "TXT" | "CNAME";
+    /** Relativo al dominio, como lo piden casi todos los paneles (`@`, `_amazonses`, `bounce`). */
+    name: string;
+    /** Nombre completo. */
+    fqdn: string;
+    value: string;
+    /** Sólo MX. */
+    priority?: number;
+    /** `requerido` para enviar; el MX raíz es `opcional` (sólo para recibir respuestas). */
+    level: "requerido" | "recomendado" | "opcional";
+    purpose: string;
+    /** Con estado: si el DNS público ya lo tiene. null = no se pudo consultar. */
+    ok?: boolean | null;
+}
+export type DomainState = "pending" | "verified" | "failed";
+/** Un dominio apartado que no se verifica (identidad + `claim`) en estos días se suelta solo. */
+export declare const DOMAIN_CLAIM_TTL_DAYS = 7;
+/**
+ * Un dominio puede estar en tenants de varios partners (la panadería que usa Formmy y Deník): la
+ * identidad de SES es una sola y cada tenant prueba que el dueño del dominio lo autorizó con su
+ * propio TXT `_mailmask` (`mailmask-claim=<token>`, registro `claim`). Ningún partner ve qué otros
+ * comparten el dominio.
+ */
+export interface PartnerDomain {
+    domain: string;
+    /** `verified` = identidad de SES verificada Y `claimed`: ya se puede enviar desde este tenant. */
+    state: DomainState;
+    /** Identidad de SES verificada (TXT `_amazonses` o DKIM). */
+    verified: boolean;
+    dkimVerified: boolean;
+    /** MAIL FROM `bounce.<dominio>` verificado: con él el SPF se alinea. */
+    mailFromDomain: string;
+    mailFromVerified: boolean;
+    /** El TXT `claim` de ESTE tenant ya se vio en el DNS público. */
+    claimed: boolean;
+    /** Si no se reclama antes, el dominio se suelta de este tenant. null = ya reclamado. */
+    claimExpiresAt: string | null;
+    /** true = la zona es de MailMask y los registros ya se escribieron solos. */
+    autoDns: boolean;
+    /**
+     * true = subdominio de la zona de respaldo del partner (`<etiqueta>.marketing.denik.me`): los
+     * registros los escribe MailMask y se verifica solo, sin que el cliente toque nada.
+     */
+    fallback: boolean;
+    records: PartnerDnsRecord[];
+    createdAt: string;
+}
+/**
+ * `POST /tenants/:externalId/domains` — 201 al agregarlo al tenant, 200 si ya estaba. 409 si el
+ * dominio es de una cuenta directa de MailMask (su dueño tendría que soltarlo).
+ *
+ * Dominio de respaldo: `<etiqueta>.<zona de respaldo del partner>` (p. ej.
+ * `estudio-aurora.marketing.denik.me`). La etiqueta es UNA sola (`FALLBACK_LABEL_RE`, sin las de
+ * `RESERVED_FALLBACK_LABELS`), es de un solo tenant (otro tenant u otro partner: 409) y cada tenant
+ * tiene a lo más un dominio de respaldo (409). 409 también si la zona todavía no está delegada.
+ */
+export interface AddDomainRequest {
+    domain: string;
+}
+export type AddDomainResponse = PartnerDomain;
+/** `GET /tenants/:externalId/domains/:domain` — consulta SES y el DNS público en vivo. */
+export type GetDomainResponse = PartnerDomain;
+/** Etiqueta de un dominio de respaldo: un solo nombre DNS en minúsculas, 1–63 caracteres. */
+export declare const FALLBACK_LABEL_RE: RegExp;
+/** Etiquetas que no se dan a un tenant: confundirían a quien lee el remitente o chocan con servicios. */
+export declare const RESERVED_FALLBACK_LABELS: readonly string[];
+/** ¿`label` sirve como etiqueta de un dominio de respaldo? */
+export declare function isValidFallbackLabel(label: string): boolean;
+/**
+ * Tipo de correo. `transactional` (confirmaciones, recordatorios, contraseñas) nunca lleva baja de
+ * un clic y no lo calla una baja del boletín. `broadcast` (boletines, promociones) lleva
+ * `List-Unsubscribe` y su baja sólo suprime `broadcast` de ESE tenant. Rebotes duros y quejas
+ * suprimen los dos.
+ */
+export type MessageStream = "transactional" | "broadcast";
+export declare const MESSAGE_STREAMS: readonly MessageStream[];
+/**
+ * Por qué un destinatario está suprimido. `bounce`, `complaint` y `manual` valen para el dominio
+ * entero y todos los streams; `unsubscribe` sólo para `broadcast` del tenant que lo envió.
+ */
+export type SuppressionReason = "bounce" | "complaint" | "unsubscribe" | "manual";
+/**
+ * Variables que se sustituyen en `subject`, `html` y `text` con marcadores `{{nombre}}` (se
+ * permiten espacios: `{{ nombre }}`). Dentro de `html` el valor se escapa (`<`, `>`, `&`, comillas);
+ * en `subject` y `text` va tal cual. Un marcador sin variable queda en cadena vacía, así que un
+ * `{{` literal en tu plantilla también se sustituye.
+ */
+export type TemplateVars = Record<string, string>;
+/** Nombre de una variable: letra o `_`, luego letras, números o `_`. */
+export declare const TEMPLATE_VAR_NAME_RE: RegExp;
+/** Por destinatario: hasta 50 variables, nombres de hasta 64 caracteres y valores de hasta 2000. */
+export declare const MAX_TEMPLATE_VARS = 50;
+export declare const MAX_TEMPLATE_VAR_NAME = 64;
+export declare const MAX_TEMPLATE_VAR_VALUE = 2000;
+/**
+ * Variable reservada: la pone MailMask en cada correo `broadcast` con la liga de baja de un clic
+ * de ESE destinatario (la misma de `List-Unsubscribe`). Si el `html` de un `broadcast` no la usa,
+ * MailMask agrega al final un pie discreto con la liga (y al `text`, una línea). En `transactional`
+ * no existe (queda vacía). No se puede mandar en `vars`.
+ */
+export declare const UNSUBSCRIBE_URL_VAR = "unsubscribe_url";
+/**
+ * Sustituye los `{{nombre}}` de una plantilla: la misma función que usa el servidor, para que el
+ * partner pueda previsualizar exactamente lo que va a salir. Con `html: true` escapa los valores.
+ */
+export declare function renderTemplate(template: string, vars: TemplateVars, opts?: {
+    html?: boolean;
+}): string;
+/** ¿La plantilla usa el marcador `{{name}}`? */
+export declare function templateUsesVar(template: string, name: string): boolean;
+/**
+ * Lo que sale para UN destinatario: sus variables en `subject`, `html` (escapadas) y `text`, y en
+ * un broadcast (`unsubscribeUrl` no null) la liga de baja en `{{unsubscribe_url}}` o, si el
+ * partner no la puso, en un pie. Un `text` ausente se queda ausente: lo deriva el pipeline del
+ * `html` ya personalizado, pie incluido.
+ */
+export declare function personalizePartnerMessage(input: {
+    subject: string;
+    html?: string;
+    text?: string;
+    vars?: TemplateVars;
+    unsubscribeUrl: string | null;
+}): {
+    subject: string;
+    html?: string;
+    text?: string;
+};
+export interface SendRequest {
+    /** `ventas@cliente.com` o `Nombre <ventas@cliente.com>`; el dominio debe ser del tenant y estar verificado. */
+    from: string;
+    to: string;
+    subject: string;
+    /** Al menos uno de `html` o `text`. Si sólo hay `html`, el texto plano se deriva. */
+    html?: string;
+    text?: string;
+    replyTo?: string;
+    /** Regresan en los eventos del webhook (`data.tags`). Ver `MAX_TAGS` y `TAG_RE`. */
+    tags?: Record<string, string>;
+    /** Default `transactional`. */
+    stream?: MessageStream;
+    /** Variables para los `{{nombre}}` de `subject`, `html` y `text` (ver `TemplateVars`). */
+    vars?: TemplateVars;
+    /** Reintentar con la misma llave en 24 h devuelve la respuesta guardada sin volver a enviar. */
+    idempotencyKey?: string;
+}
+/** `POST /tenants/:externalId/send` — 200. Con `Idempotent-Replayed: true` si fue repetición. */
+export interface SendResponse {
+    /** Message-ID del correo (con ángulos). */
+    messageId: string;
+    /** Id de SES; es el que aparece en los eventos. En modo de prueba empieza con `test-`. */
+    sesMessageId: string;
+    status: "sent";
+    /** Sólo en modo de prueba (`X-MailMask-Test: 1`): no salió nada. */
+    test?: true;
+}
+/** Un destinatario del lote con sus variables (`{{nombre}}` en `subject`, `html` y `text`). */
+export interface BatchRecipient {
+    to: string;
+    vars?: TemplateVars;
+}
+export interface BatchRequest {
+    from: string;
+    /** Plantillas: `{{nombre}}` se sustituye por destinatario (ver `TemplateVars`). */
+    subject: string;
+    html: string;
+    text?: string;
+    replyTo?: string;
+    tags?: Record<string, string>;
+    /**
+     * 1 a `MAX_BATCH_RECIPIENTS`: el correo pelado o `{ to, vars }`; se pueden mezclar. Los
+     * suprimidos se saltan (cuentan en `skippedSuppressed`).
+     */
+    recipients: Array<string | BatchRecipient>;
+    /** Default `broadcast` (lleva baja de un clic por destinatario). */
+    stream?: MessageStream;
+    idempotencyKey?: string;
+}
+export type BatchState = "queued" | "processing" | "completed" | "failed";
+export interface BatchStatus {
+    batchId: string;
+    status: BatchState;
+    stream: MessageStream;
+    total: number;
+    sent: number;
+    failed: number;
+    skippedSuppressed: number;
+    /**
+     * Lo que pasó después de enviar, contado con los mismos eventos que llegan al webhook (entregas,
+     * rebotes permanentes y quejas de SES; bajas de un clic desde un correo de este lote). Crecen
+     * durante horas después de `completed`; el lote se consulta hasta 7 días después de crearlo.
+     */
+    delivered: number;
+    bounced: number;
+    complained: number;
+    unsubscribed: number;
+    lastError: string | null;
+    createdAt: string;
+    completedAt: 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).
+     */
+    test?: true;
+}
+/** `POST /tenants/:externalId/batch` — 202. */
+export type BatchResponse = BatchStatus;
+/** `GET /tenants/:externalId/batch/:batchId` */
+export type GetBatchResponse = BatchStatus;
+export interface TenantUsage {
+    externalId: string;
+    sent: number;
+    delivered: number;
+    bounced: number;
+    complained: number;
+    unsubscribed: number;
+}
+/** `GET /usage?month=YYYY-MM` (default: el mes en curso, UTC). Activo = al menos un envío en el mes. */
+export interface UsageResponse {
+    month: string;
+    activeTenants: number;
+    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;
+    events: PartnerWebhookEvent[];
+}
+/**
+ * `PUT /webhook` — https y host público. Cambiar la URL NO cambia el secreto: el `whsec_…` se crea
+ * la primera vez (y sólo entonces viene en la respuesta) y se rota aparte.
+ */
+export interface SetWebhookRequest {
+    url: string;
+}
+export interface SetWebhookResponse {
+    url: string;
+    /** `whsec_…` sólo la primera vez que se configura; null si ya existía. */
+    secret: string | null;
+}
+/**
+ * `POST /webhook/rotate-secret` — secreto nuevo, que se ve UNA vez. Durante la gracia (0–10080 min,
+ * default 1440 = 24 h) cada entrega lleva dos firmas, la nueva y la vieja, separadas por coma.
+ */
+export interface RotateWebhookSecretRequest {
+    graceMinutes?: number;
+}
+export interface RotateWebhookSecretResponse {
+    secret: string;
+    /** Hasta cuándo se sigue firmando también con el secreto anterior. null = sin gracia. */
+    previousValidUntil: string | null;
+}
+/** `POST /webhook/test` — encola un `ping`. 202. */
+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"];
+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: {
+    readonly event: "X-MailMask-Event";
+    readonly delivery: "X-MailMask-Delivery";
+    /** MILISEGUNDOS Unix, en texto (distinto de `X-MailMask-Ts` de las peticiones). */
+    readonly timestamp: "X-MailMask-Timestamp";
+    /**
+     * `sha256=` + hex de HMAC-SHA256(secreto `whsec_…`, `webhookSignatureBase(...)`). Durante la gracia
+     * de una rotación vienen dos separadas por coma (`sha256=<nueva>,sha256=<vieja>`): el receptor
+     * acepta la entrega si CUALQUIERA coincide con su secreto.
+     */
+    readonly signature: "X-MailMask-Signature";
+};
+/** Tolerancia del receptor al verificar: 5 min, borde incluido. */
+export declare const WEBHOOK_TOLERANCE_MS: number;
+/** Texto que firma MailMask al entregar: `${timestamp}.${rawBody}` (contrato de docs/agents/firma-webhooks.md). */
+export declare function webhookSignatureBase(timestamp: string, rawBody: string): string;
+export interface EmailEventBase {
+    /** Dominio remitente (o receptor, en `email.received`). */
+    domain: string;
+    messageId: string | null;
+    sesMessageId: string | null;
+    subject: string | null;
+    tags: Record<string, string>;
+}
+export interface PartnerEventData {
+    "email.sent": EmailEventBase & {
+        from: string;
+        to: string;
+        batchId: string | null;
+        stream: MessageStream;
+    };
+    "email.delivered": EmailEventBase & {
+        recipient: string;
+        smtpResponse: string | null;
+    };
+    "email.bounced": EmailEventBase & {
+        recipient: string;
+        bounceType: "Permanent";
+        diagnostic: string | null;
+    };
+    "email.complained": EmailEventBase & {
+        recipient: string;
+        feedbackType: string | null;
+    };
+    "email.received": {
+        domain: string;
+        from: string;
+        to: string;
+        subject: string;
+        messageId: string | null;
+        inReplyTo: string | null;
+    };
+    /** La baja de un clic de un `broadcast`: suprime sólo `broadcast` de este tenant. */
+    "contact.unsubscribed": {
+        domain: string;
+        email: string;
+        source: "one-click" | "page";
+        stream: "broadcast";
+    };
+    "tenant.paused": {
+        reason: string;
+        by: PausedBy;
+        window?: {
+            sent: number;
+            bounceRate: number;
+            complaintRate: number;
+        };
+    };
+    "tenant.resumed": {
+        by: "partner" | "mailmask";
+    };
+    "domain.verified": {
+        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 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;
+    event: E;
+    externalId: string | null;
+    /** ISO del momento en que ocurrió. */
+    timestamp: string;
+    data: PartnerEventData[E];
+}
+/**
+ * Política de reputación de SES para los tenants del partner. Strict pausa el envío antes ante
+ * rebotes y quejas; Standard es la de AWS por defecto.
+ */
+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. MailMask (admin) con `?all=1`: todos, con `tenants`. */
+export interface PartnerSummary {
+    id: string;
+    name: string;
+    plan: {
+        includedTenants: number;
+        sendsPerTenantMonth: number;
+    };
+    webhookUrl: string | null;
+    disabledAt: string | null;
+    createdAt: string;
+    /** La que fijó MailMask; null = automática (Strict el primer mes, Standard después). */
+    reputationPolicy: ReputationPolicy | null;
+    /** La que se aplica hoy a sus tenants. */
+    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 {
+    name: string;
+    /** Cuenta de MailMask que será dueña del partner; debe existir. */
+    ownerEmail: string;
+    plan?: Partial<PartnerSummary["plan"]>;
+    reputationPolicy?: ReputationPolicy | null;
+}
+/** `PUT /api/partners/:partnerId/reputation-policy` — sólo MailMask (admin); null = automática. */
+export interface SetReputationPolicyRequest {
+    policy: ReputationPolicy | null;
+}
+/**
+ * `PUT /api/partners/:partnerId/fallback-zone` — sólo MailMask (admin). Crea (o adopta) la hosted
+ * zone de Route 53 para `zone` y devuelve los 4 NS que el partner tiene que delegar en SU DNS
+ * (registros NS de `zone` en la zona padre). Repetirlo con la misma zona es idempotente; cambiarla
+ * por otra responde 409.
+ */
+export interface SetFallbackZoneRequest {
+    zone: string;
+}
+/** `PUT` y `GET /api/partners/:partnerId/fallback-zone` (el GET también lo ve el dueño). */
+export interface FallbackZone {
+    zone: string;
+    hostedZoneId: string;
+    /** Los NS de Route 53 que hay que delegar (NS de `zone` en la zona padre). */
+    nameservers: string[];
+    /** El DNS público ya responde con nuestros NS: los dominios de respaldo se pueden verificar. */
+    delegated: boolean;
+    /** Los NS que hoy ve el DNS público para `zone` (vacío = todavía no hay delegación). */
+    observedNameservers: string[];
+    /** Primera vez que se vio la delegación. */
+    delegatedAt: string | null;
+}
+export interface PartnerCredential {
+    keyId: string;
+    label: string;
+    createdAt: string;
+    rotatedAt: string | null;
+    /** Hasta cuándo sigue firmando el secreto anterior tras rotar. */
+    prevValidUntil: string | null;
+    revokedAt: string | null;
+    lastUsedAt: string | null;
+}
+/** `GET /api/partners/:partnerId/credentials` */
+export interface ListCredentialsResponse {
+    credentials: PartnerCredential[];
+}
+/** `POST /api/partners/:partnerId/credentials` — 201; el secreto `mms_…` se ve una vez. */
+export interface CreateCredentialRequest {
+    label?: string;
+}
+export type CreateCredentialResponse = PartnerCredential & {
+    secret: string;
+};
+/** `POST /api/partners/:partnerId/credentials/:keyId/rotate` — gracia 0–10080 min (default 60). */
+export interface RotateCredentialRequest {
+    graceMinutes?: number;
+}
+export type RotateCredentialResponse = PartnerCredential & {
+    secret: string;
+};
+/** `DELETE /api/partners/:partnerId/credentials/:keyId` — inmediato, sin vuelta. */
+export type RevokeCredentialResponse = PartnerCredential;
+/** Rutas firmadas, relativas a `PARTNER_API_PREFIX`. `:x` = parámetro codificado con encodeURIComponent. */
+export declare const PARTNER_ROUTES: {
+    readonly putTenant: {
+        readonly method: "PUT";
+        readonly path: "/tenants/:externalId";
+    };
+    readonly listTenants: {
+        readonly method: "GET";
+        readonly path: "/tenants";
+    };
+    readonly getTenant: {
+        readonly method: "GET";
+        readonly path: "/tenants/:externalId";
+    };
+    readonly deleteTenant: {
+        readonly method: "DELETE";
+        readonly path: "/tenants/:externalId";
+    };
+    readonly pauseTenant: {
+        readonly method: "POST";
+        readonly path: "/tenants/:externalId/pause";
+    };
+    readonly resumeTenant: {
+        readonly method: "POST";
+        readonly path: "/tenants/:externalId/resume";
+    };
+    readonly addDomain: {
+        readonly method: "POST";
+        readonly path: "/tenants/:externalId/domains";
+    };
+    readonly getDomain: {
+        readonly method: "GET";
+        readonly path: "/tenants/:externalId/domains/:domain";
+    };
+    readonly send: {
+        readonly method: "POST";
+        readonly path: "/tenants/:externalId/send";
+    };
+    readonly batch: {
+        readonly method: "POST";
+        readonly path: "/tenants/:externalId/batch";
+    };
+    readonly getBatch: {
+        readonly method: "GET";
+        readonly path: "/tenants/:externalId/batch/:batchId";
+    };
+    readonly usage: {
+        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";
+    };
+    readonly setWebhook: {
+        readonly method: "PUT";
+        readonly path: "/webhook";
+    };
+    readonly testWebhook: {
+        readonly method: "POST";
+        readonly path: "/webhook/test";
+    };
+    readonly rotateWebhookSecret: {
+        readonly method: "POST";
+        readonly path: "/webhook/rotate-secret";
+    };
+};
+/** Rutas de administración (sin firma: sesión o `Authorization: Bearer mk_…`). Absolutas. */
+export declare const PARTNER_ADMIN_ROUTES: {
+    readonly listPartners: {
+        readonly method: "GET";
+        readonly path: "/api/partners";
+    };
+    readonly createPartner: {
+        readonly method: "POST";
+        readonly path: "/api/partners";
+    };
+    readonly setReputationPolicy: {
+        readonly method: "PUT";
+        readonly path: "/api/partners/:partnerId/reputation-policy";
+    };
+    /** Sólo MailMask (admin): levanta cualquier pausa, incluida la de reputación. */
+    readonly resumeTenant: {
+        readonly method: "POST";
+        readonly path: "/api/partners/:partnerId/tenants/:externalId/resume";
+    };
+    /** Sólo MailMask (admin): crea o adopta la zona de respaldo y devuelve los NS a delegar. */
+    readonly setFallbackZone: {
+        readonly method: "PUT";
+        readonly path: "/api/partners/:partnerId/fallback-zone";
+    };
+    /** La zona de respaldo y si la delegación ya se ve en el DNS público. */
+    readonly getFallbackZone: {
+        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";
+    };
+    readonly createCredential: {
+        readonly method: "POST";
+        readonly path: "/api/partners/:partnerId/credentials";
+    };
+    readonly rotateCredential: {
+        readonly method: "POST";
+        readonly path: "/api/partners/:partnerId/credentials/:keyId/rotate";
+    };
+    readonly revokeCredential: {
+        readonly method: "DELETE";
+        readonly path: "/api/partners/:partnerId/credentials/:keyId";
+    };
+};