@easybits.cloud/mailmask 0.4.12 → 0.6.1

package/dist/partner.d.ts

@@ -0,0 +1,371 @@
+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";
+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";
+/** Metadatos de la respuesta que no vienen en el cuerpo. */
+export interface PartnerErrorMeta {
+    requestId?: string;
+    retryAfterMs?: number | null;
+    cause?: unknown;
+}
+/**
+ * Error de la API de partners. Extiende el `MailMaskError` del SDK (mismo `instanceof`) y suma
+ * el `code` del contrato, el cuerpo completo, `kind`, `requestId` y `retryable`. Nunca contiene
+ * la credencial: el mensaje sale del servidor (o del runtime, en errores de red).
+ */
+export declare class PartnerApiError extends MailMaskError {
+    code: PartnerErrorCode | undefined;
+    body: Partial<PartnerErrorBody>;
+    kind: PartnerErrorKind;
+    /** `Retry-After` de la respuesta en ms; null si no vino. */
+    retryAfterMs: number | null;
+    constructor(status: number, message: string, body?: Partial<PartnerErrorBody>, meta?: PartnerErrorMeta);
+}
+/** 401: firma ausente, mala o vencida; credencial revocada o inexistente. */
+export declare class AuthError extends PartnerApiError {
+    name: string;
+    kind: PartnerErrorKind;
+    /**
+     * Diferencia entre el reloj de MailMask (header `Date` de la respuesta) y el tuyo, en ms
+     * (positivo = tu reloj va atrasado). null si la respuesta no trajo `Date`. Con más de
+     * `PARTNER_SIGNATURE_TOLERANCE_S` segundos la firma nunca va a pasar.
+     */
+    clockSkewMs: number | null;
+}
+/** 403: partner desactivado o tenant suspendido por MailMask. */
+export declare class ForbiddenError extends PartnerApiError {
+    name: string;
+    kind: PartnerErrorKind;
+}
+/**
+ * 403 `reputation_hold`: `tenants.resume` sobre una pausa que puso MailMask o SES por reputación
+ * (`pausedBy` `mailmask` o `ses`). No se arregla reintentando: la levanta MailMask tras revisar el caso.
+ */
+export declare class ReputationHoldError extends ForbiddenError {
+    name: string;
+    kind: PartnerErrorKind;
+}
+/** 404: el recurso no existe para este partner. */
+export declare class NotFoundError extends PartnerApiError {
+    name: string;
+    kind: PartnerErrorKind;
+}
+/** 409: dominio de otra cuenta/tenant, máximo de credenciales, estado incompatible. */
+export declare class ConflictError extends PartnerApiError {
+    name: string;
+    kind: PartnerErrorKind;
+}
+/** 422: validación; `field` dice qué campo falló. */
+export declare class ValidationError extends PartnerApiError {
+    name: string;
+    kind: PartnerErrorKind;
+    get field(): string | undefined;
+}
+/**
+ * 422 `recipient_suppressed`: el destinatario está suprimido para ese stream (rebote, queja, baja o
+ * manual). No es un error del cuerpo: no reintentes; marca a la persona en tu sistema.
+ */
+export declare class RecipientSuppressedError extends PartnerApiError {
+    name: string;
+    kind: PartnerErrorKind;
+    get reason(): SuppressionReason | undefined;
+    get stream(): MessageStream | undefined;
+    get recipient(): string | undefined;
+}
+/** 423: el tenant está en pausa; no sale nada hasta `tenants.resume`. */
+export declare class PausedError extends PartnerApiError {
+    name: string;
+    kind: PartnerErrorKind;
+}
+/**
+ * 429 `quota_exceeded`: cuota mensual agotada; trae `limit` y `resetsAt` y NO se reintenta. El 429
+ * de ritmo es la subclase `RateLimitError`.
+ */
+export declare class QuotaError extends PartnerApiError {
+    name: string;
+    kind: PartnerErrorKind;
+    get limit(): number | undefined;
+    get resetsAt(): string | undefined;
+}
+/**
+ * 429 `rate_limited`: demasiadas peticiones. El cliente ya reintentó respetando `Retry-After`;
+ * si llega hasta ti, se acabaron los reintentos. Extiende `QuotaError` por compatibilidad (0.5).
+ */
+export declare class RateLimitError extends QuotaError {
+    name: string;
+    kind: PartnerErrorKind;
+}
+/** No hubo respuesta: DNS, conexión rechazada o cortada. `status` 0. */
+export declare class NetworkError extends PartnerApiError {
+    name: string;
+    kind: PartnerErrorKind;
+    constructor(message: string, cause?: unknown);
+}
+/** Se agotó `timeoutMs` esperando la respuesta. `status` 0. */
+export declare class TimeoutError extends NetworkError {
+    name: string;
+    kind: PartnerErrorKind;
+}
+/** Firma una petición de partner; expuesta para quien no use el cliente (o para pruebas). */
+export declare function signPartnerRequest(opts: {
+    keyId: string;
+    secret: string;
+    method: string;
+    pathAndQuery: string;
+    rawBody?: string;
+    ts?: number;
+}): Promise<Record<string, string>>;
+/** Lo que recibe `onRetry` antes de cada espera. */
+export interface PartnerRetryInfo {
+    /** 1 = primer reintento. */
+    attempt: number;
+    delayMs: number;
+    method: string;
+    /** Ruta sin host (la credencial nunca va aquí). */
+    path: string;
+    error: PartnerApiError;
+}
+/** Ajustes de transporte compartidos por `MailMaskPartner` y `MailMaskPartnerAdmin`. */
+export interface PartnerTransportConfig {
+    /** Default `https://www.mailmask.studio`. */
+    baseUrl?: string;
+    /**
+     * Reintentos ante 429 de ritmo, 5xx, red y tiempo agotado (default 3, máximo 10). Sólo se
+     * reintentan peticiones idempotentes (GET, PUT, DELETE, pausa, reanudar, alta de dominio) y los
+     * envíos, que siempre llevan `idempotencyKey`. `webhook.rotateSecret` y `webhook.test` no.
+     */
+    maxRetries?: number;
+    /** Base del backoff exponencial en ms (default 500), con jitter: 250–500, 500–1000, 1000–2000… */
+    retryBaseMs?: number;
+    /**
+     * Tope de espera entre reintentos en ms (default 30 000). Si `Retry-After` pide más, no se
+     * reintenta: el error sale con `retryAfterMs` para que decidas tú.
+     */
+    retryMaxDelayMs?: number;
+    /** Tiempo máximo por intento, en ms (default 30 000). Al agotarse lanza `TimeoutError`. */
+    timeoutMs?: number;
+    /** Se llama antes de cada reintento (para tus logs; no trae secretos). */
+    onRetry?: (info: PartnerRetryInfo) => void;
+    /** fetch alterno (pruebas, runtimes raros). */
+    fetch?: typeof fetch;
+}
+export interface MailMaskPartnerConfig extends PartnerTransportConfig {
+    /** Id público de la credencial, `mmk_…`. */
+    keyId: string;
+    /** Secreto `mms_…`. Sólo en el servidor del partner, nunca en el navegador. */
+    secret: string;
+    /**
+     * Modo de prueba: manda `X-MailMask-Test: 1` en cada petición. `send` y `batch` validan todo y
+     * responden con `test: true` sin enviar, sin cobrar y sin eventos. Úsalo en desarrollo y CI.
+     * También se puede pedir por envío con `{ test: true }` en las opciones de `send`/`batch`.
+     */
+    test?: boolean;
+}
+export interface PartnerResponseMeta {
+    status: number;
+    /** true si el servidor devolvió la respuesta guardada de una `idempotencyKey` repetida. */
+    idempotentReplayed: boolean;
+}
+/** Opciones por envío. */
+export interface PartnerSendOptions {
+    /** Modo de prueba sólo para esta llamada (igual que `test` del constructor). */
+    test?: boolean;
+}
+export declare class MailMaskPartner {
+    readonly keyId: string;
+    private transport;
+    private test;
+    tenants: PartnerTenantsResource;
+    domains: PartnerDomainsResource;
+    webhook: PartnerWebhookResource;
+    constructor(config: MailMaskPartnerConfig);
+    /** Base URL efectiva (sin barra final). */
+    get baseUrl(): string;
+    /**
+     * Petición firmada. Cada intento se firma de nuevo (ts fresco) con el MISMO cuerpo, así que la
+     * `idempotencyKey` del cuerpo viaja idéntica en los reintentos.
+     * @internal
+     */
+    request<T>(method: string, path: string, body?: unknown, extraHeaders?: Record<string, string>, opts?: {
+        idempotent?: boolean;
+        test?: boolean;
+    }): Promise<{
+        data: T;
+        meta: PartnerResponseMeta;
+    }>;
+    /**
+     * Manda un correo a nombre de un tenant. Pone `idempotencyKey` si no viene (la misma en cada
+     * reintento). `stream` default `transactional` (sin baja de un clic); usa `broadcast` para
+     * boletines. `vars` sustituye los `{{nombre}}`. Un destinatario suprimido lanza `RecipientSuppressedError`.
+     */
+    send(externalId: string, input: SendRequest, opts?: PartnerSendOptions): Promise<SendResponse & {
+        idempotencyKey: string;
+        replayed: boolean;
+    }>;
+    /**
+     * Encola un lote (hasta 10,000 destinatarios: correos pelados o `{ to, vars }`). Pone
+     * `idempotencyKey` si no viene. `stream` default `broadcast` (cada correo lleva baja de un clic);
+     * los suprimidos se saltan.
+     */
+    batch(externalId: string, input: BatchRequest, opts?: PartnerSendOptions): Promise<BatchStatus & {
+        idempotencyKey: string;
+        replayed: boolean;
+    }>;
+    /** 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>;
+    /** Uso del mes (`YYYY-MM`, default el mes en curso UTC): tenants activos y envíos. */
+    usage(opts?: {
+        month?: string;
+    }): Promise<UsageResponse>;
+}
+declare class PartnerTenantsResource {
+    private c;
+    constructor(c: MailMaskPartner);
+    /** Crea o actualiza el tenant (idempotente por `externalId`). */
+    put(externalId: string, input?: PutTenantRequest): Promise<Tenant>;
+    get(externalId: string): Promise<Tenant>;
+    /** Una página de tenants; sigue `nextCursor` para la siguiente. */
+    list(query?: ListTenantsQuery): Promise<ListTenantsResponse>;
+    /**
+     * Borra el tenant y suelta sus dominios (los que nadie más usa se borran con sus recursos en SES).
+     * Sin vuelta atrás. `ConflictError` si está en pausa por reputación.
+     */
+    delete(externalId: string): Promise<DeleteTenantResponse>;
+    pause(externalId: string, reason?: string): Promise<Tenant>;
+    /**
+     * Levanta una pausa que puso el partner (`pausedBy: "partner"`). Sobre una pausa por reputación
+     * (`mailmask` o `ses`) lanza `ReputationHoldError`.
+     */
+    resume(externalId: string): Promise<Tenant>;
+}
+declare class PartnerDomainsResource {
+    private c;
+    constructor(c: MailMaskPartner);
+    /** Da de alta el dominio en el tenant y devuelve los registros DNS a pegar. */
+    add(externalId: string, domain: string): Promise<PartnerDomain>;
+    /** Estado en vivo (SES y DNS público) de cada registro. */
+    status(externalId: string, domain: string): Promise<PartnerDomain>;
+}
+declare class PartnerWebhookResource {
+    private c;
+    constructor(c: MailMaskPartner);
+    get(): Promise<WebhookConfig>;
+    /**
+     * Configura la URL. `secret` (`whsec_…`) sólo viene la primera vez; después es null porque cambiar
+     * la URL no rota el secreto (para eso, `rotateSecret`).
+     */
+    set(input: SetWebhookRequest): Promise<SetWebhookResponse>;
+    /**
+     * Secreto nuevo (se ve UNA vez). Durante la gracia (default 24 h, 0–10080 min) cada entrega lleva
+     * las dos firmas: despliega el nuevo y pasa los dos a `verifyWebhook` mientras tanto. No se
+     * reintenta solo: un segundo intento rotaría otra vez y el secreto de la respuesta perdida no
+     * lo vería nadie.
+     */
+    rotateSecret(input?: RotateWebhookSecretRequest): Promise<RotateWebhookSecretResponse>;
+    /** Encola un `ping` al webhook. No se reintenta solo (un reintento encolaría otro ping). */
+    test(): Promise<TestWebhookResponse>;
+}
+/** Headers como `Headers` de fetch, o como objeto plano de Node/Express (llaves en minúsculas o no). */
+export type WebhookHeadersInput = Headers | Record<string, string | string[] | undefined>;
+/**
+ * Verifica una entrega del webhook del partner con el cuerpo CRUDO (sin parsear). Devuelve el
+ * evento ya parseado si la firma es válida y el timestamp está a ≤ 5 min (borde incluido); `null`
+ * si no. Compara en tiempo constante.
+ *
+ * Rotación: `secret` acepta uno o dos secretos (`[nuevo, viejo]`), y el header puede traer dos
+ * firmas separadas por coma (`sha256=<nueva>,sha256=<vieja>`). Basta con que una coincida.
+ */
+export declare function verifyWebhook(opts: {
+    rawBody: string;
+    headers: WebhookHeadersInput;
+    secret: string | readonly string[];
+    /** Default 5 min, como el contrato. */
+    toleranceMs?: number;
+    /** Reloj alterno (pruebas). */
+    now?: number;
+}): Promise<PartnerWebhookPayload | null>;
+/**
+ * Handler listo para runtimes con `Request`/`Response` (Workers, Deno, Bun, Next.js, Hono): verifica
+ * la firma con el cuerpo crudo y llama a `onEvent`. Responde 401 si la firma no cuadra, 200 si
+ * `onEvent` terminó bien y 500 si lanzó (MailMask reintenta la entrega). Deduplica tú por `event.id`.
+ */
+export declare function createWebhookHandler(opts: {
+    secret: string | readonly string[];
+    onEvent: (event: PartnerWebhookPayload) => unknown | Promise<unknown>;
+    toleranceMs?: number;
+}): (request: Request) => Promise<Response>;
+/** Nombres de los `{{marcadores}}` de una plantilla, sin repetir. */
+export declare function templateVarNames(template: string): string[];
+/**
+ * Valida unas `vars` con las mismas reglas que el servidor (máx. 50, nombres `[a-zA-Z_]\w*` de hasta
+ * 64, valores de texto de hasta 2000, `unsubscribe_url` reservada). Devuelve el problema o null.
+ */
+export declare function templateVarsProblem(vars: unknown): string | null;
+/** Resultado de `previewMessage`. */
+export interface MessagePreview {
+    subject: string;
+    html?: string;
+    text?: string;
+    stream: MessageStream;
+    /** true si MailMask agregará el pie de baja (broadcast cuyo html/text no usa `{{unsubscribe_url}}`). */
+    unsubscribeFooter: boolean;
+    /** Marcadores de la plantilla sin variable: saldrán vacíos. */
+    missingVars: string[];
+    /** Variables que mandaste y ninguna plantilla usa. */
+    unusedVars: string[];
+}
+/**
+ * Lo que va a salir para UN destinatario, con la MISMA función que usa el servidor
+ * (`personalizePartnerMessage` del contrato): variables, escape en html y, en `broadcast`, la liga
+ * de baja (`unsubscribeUrl`, default una liga de ejemplo) o el pie que MailMask agrega. Sin red.
+ */
+export declare function previewMessage(input: {
+    subject: string;
+    html?: string;
+    text?: string;
+    stream?: MessageStream;
+    vars?: TemplateVars;
+}, opts?: {
+    unsubscribeUrl?: string;
+}): MessagePreview;
+export interface MailMaskPartnerAdminConfig extends PartnerTransportConfig {
+    /** Llave `mk_…` del DUEÑO del partner (nunca la credencial `mmk_`/`mms_`). */
+    apiKey: string;
+}
+/**
+ * Rutas de administración (`/api/partners/…`): credenciales del partner y, sólo para cuentas de
+ * MailMask, alta de partners, política de reputación y levantar pausas por reputación. Mismos
+ * errores tipados, timeout y reintentos (sólo en lecturas) que `MailMaskPartner`.
+ */
+export declare class MailMaskPartnerAdmin {
+    private transport;
+    constructor(config: MailMaskPartnerAdminConfig);
+    private req;
+    /** Los partners de la cuenta. */
+    listPartners(): Promise<PartnerSummary[]>;
+    /** Sólo MailMask (admin). */
+    createPartner(input: CreatePartnerRequest): Promise<PartnerSummary>;
+    /** Sólo MailMask (admin); null = automática (Strict el primer mes, Standard después). */
+    setReputationPolicy(partnerId: string, policy: ReputationPolicy | null): Promise<PartnerSummary>;
+    /** Sólo MailMask (admin): levanta cualquier pausa, también la de reputación. */
+    resumeTenant(partnerId: string, externalId: string): 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.
+     */
+    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>;
+    listCredentials(partnerId: string): Promise<ListCredentialsResponse>;
+    /** El secreto `mms_…` viene UNA vez en la respuesta. */
+    createCredential(partnerId: string, input?: CreateCredentialRequest): Promise<CreateCredentialResponse>;
+    /** Secreto nuevo (una vez); el anterior sigue firmando `graceMinutes` (default 60). */
+    rotateCredential(partnerId: string, keyId: string, input?: RotateCredentialRequest): Promise<RotateCredentialResponse>;
+    /** Inmediato y sin vuelta. */
+    revokeCredential(partnerId: string, keyId: string): Promise<RevokeCredentialResponse>;
+}

package/package.json

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