@easybits.cloud/mailmask 0.4.8 → 0.4.10

package/README.md

@@ -81,6 +81,15 @@ import { verifyWebhookSignature } from "@easybits.cloud/mailmask";
 const ok = await verifyWebhookSignature(secret, { signature: req.headers["x-mailmask-signature"], timestamp: req.headers["x-mailmask-timestamp"] }, rawBody);
 ```
 
+## TypeScript
+
+Los tipos publicados se pueden consumir desde **TypeScript 4.9 en adelante**, también con
+`moduleResolution: node` (el clásico, sin `exports`). El paquete se compila con TypeScript 7, pero
+el build baja la única sintaxis que un TS viejo no entiende (`export type *`, de TS 5.0) a su
+equivalente (`scripts/postbuild-dts.mjs`): sin eso, un consumidor con TS ≤ 4.9 falla en su propia
+compilación con `TS1383` y desde aquí no se nota. `npm run check:consumer` arma el paquete con
+`npm pack` y lo compila en un proyecto con TypeScript 4.9.5 para confirmarlo.
+
 ## Docs
 
 Full API reference and examples: https://mailmask.studio/docs

package/dist/client.d.ts

@@ -0,0 +1,427 @@
+import type { MailMaskConfig, Domain, DomainCreated, DomainVerification, Alias, AliasCreated, MailboxCreated, CreateAliasInput, UpdateAliasInput, Rule, CreateRuleInput, UpdateRuleInput, EmailLog, SendEmailInput, BulkSendInput, BulkJob, BulkJobCreated, SmtpCredential, SmtpCredentialCreated, ApiKey, SendOptions, UploadAttachmentInput, UploadedAttachment, Suppression, Webhook, WebhookCreated, CreateWebhookInput, UpdateWebhookInput, WebhookDelivery, DnsRecordType, DnsListResponse, DnsZoneCreated, DnsDelegation, DnsImportResult, DnsChangeResult, DnsPreset, DnsPresetPreview, DnsSetup, WebsiteStatus, PublishEasyBitsSiteInput, EasyBitsPublishResult, EasyBitsSiteStatus, EasyBitsUnpublishResult, BillingStatus, AddonsResponse, CheckoutLink, DomainSearchResult, TldPrice, DomainRegistrationCreated, DomainRegistration, TransferCheck, TransferDnsInventory, RenewalLink, DomainMember, DomainInvite, CannedReply, AccountProfile, AccountMe, AccountExport, InboxPage, InboxListOptions, InboxConversation, InboxConversationDetail, InboxComposeInput, InboxReplyInput, InboxUpdateInput, InboxNote, OrdersPage, ReferralStats, UploadedEmailImage } from "./types.js";
+declare class MailMaskError extends Error {
+    status: number;
+    constructor(status: number, message: string);
+}
+export declare class MailMask {
+    private baseUrl;
+    private apiKey;
+    domains: DomainsResource;
+    /** Las direcciones del dominio (máscaras), con reenvío, buzón o ambos. */
+    addresses: AliasesResource;
+    /** @deprecated Usa `addresses`; es el mismo recurso y no se va a retirar. */
+    aliases: AliasesResource;
+    rules: RulesResource;
+    logs: LogsResource;
+    send: SendResource;
+    attachments: AttachmentsResource;
+    suppressions: SuppressionsResource;
+    webhooks: WebhooksResource;
+    smtp: SmtpResource;
+    apiKeys: ApiKeysResource;
+    dns: DnsResource;
+    billing: BillingResource;
+    registrations: RegistrationsResource;
+    transfers: TransfersResource;
+    members: MembersResource;
+    signature: SignatureResource;
+    canned: CannedResource;
+    account: AccountResource;
+    inbox: InboxResource;
+    referrals: ReferralsResource;
+    constructor(config: MailMaskConfig);
+}
+type Req = <T>(path: string, opts?: RequestInit) => Promise<T>;
+declare class DomainsResource {
+    private req;
+    constructor(req: Req);
+    list(): Promise<Domain[]>;
+    get(id: string): Promise<Domain>;
+    create(domain: string): Promise<DomainCreated>;
+    delete(id: string): Promise<{
+        ok: boolean;
+    }>;
+    health(id: string): Promise<Record<string, unknown>>;
+    verify(id: string): Promise<DomainVerification>;
+    /** Registros a pegar en el registrador. Con `live` los compara con el DNS público y deduce el panel. */
+    dnsSetup(id: string, opts?: {
+        live?: boolean;
+    }): Promise<DnsSetup>;
+    /** Logo de la firma (PNG, JPG o WebP; máx. 500 KB). Se ve en todo correo en markdown. */
+    setLogo(id: string, file: Blob, filename?: string): Promise<{
+        ok: boolean;
+        logoUrl: string;
+    }>;
+    /** Logo desde un adjunto del chat del asistente (URL firmada de `/api/asistente/files/*`). */
+    setLogoFromUrl(id: string, url: string): Promise<{
+        ok: boolean;
+        logoUrl: string;
+    }>;
+    removeLogo(id: string): Promise<{
+        ok: boolean;
+    }>;
+    /**
+     * Publica un sitio de EasyBits en el dominio: lo da de alta en EasyBits, escribe sus
+     * registros (sin tocar el correo), verifica y, en la raíz, lo asigna. Requiere la cuenta
+     * de EasyBits conectada en el navegador; sin ella, 409 con la liga para conectarla.
+     */
+    publishEasyBitsSite(id: string, input: PublishEasyBitsSiteInput): Promise<EasyBitsPublishResult>;
+    /** Quita el sitio: el DNS vuelve a como estaba (lo que cambiaste después no se toca) y se limpia EasyBits. */
+    unpublishEasyBitsSite(id: string): Promise<EasyBitsUnpublishResult>;
+    /** Qué sitio de EasyBits está publicado en el dominio, si alguno, y si la cuenta está conectada. */
+    easyBitsSiteStatus(id: string): Promise<EasyBitsSiteStatus>;
+    /** Imagen para incrustar en un correo saliente (PNG, JPG, GIF o WebP; máx. 2 MB). Efímera: se borra tras enviarse o por el barrido diario. */
+    uploadImage(id: string, file: Blob, filename?: string): Promise<UploadedEmailImage>;
+}
+declare class DnsResource {
+    private req;
+    constructor(req: Req);
+    list(domainId: string): Promise<DnsListResponse>;
+    createZone(domainId: string): Promise<DnsZoneCreated>;
+    delegation(domainId: string): Promise<DnsDelegation>;
+    import(domainId: string): Promise<DnsImportResult>;
+    /** Reemplaza el conjunto: `values` sustituye por completo lo que hubiera en ese nombre y tipo. */
+    upsert(domainId: string, record: {
+        name: string;
+        type: DnsRecordType;
+        values: string[];
+        ttl?: number;
+    }): Promise<DnsChangeResult>;
+    delete(domainId: string, name: string, type: DnsRecordType): Promise<{
+        ok: boolean;
+        changeId: string;
+    }>;
+    /** Con 'easybits' publica un sitio de la cuenta conectada (`opts.websiteId`), igual que `domains.publishEasyBitsSite`. */
+    preset(domainId: string, preset: DnsPreset, target?: string, subdomain?: string, opts?: {
+        websiteId?: string;
+        placement?: "apex" | "subdomain";
+    }): Promise<DnsChangeResult>;
+    /** Vista previa de una plantilla: lo que escribiría y lo que hay hoy, sin tocar nada. */
+    presetPreview(domainId: string, preset: DnsPreset, target?: string, subdomain?: string, opts?: {
+        websiteId?: string;
+        placement?: "apex" | "subdomain";
+    }): Promise<DnsPresetPreview>;
+    /** A dónde apunta el sitio (raíz, www y subdominios), qué plataforma es, qué está mal y si responde por HTTPS. */
+    website(domainId: string): Promise<WebsiteStatus>;
+}
+declare class AliasesResource {
+    private req;
+    private raw;
+    constructor(req: Req, raw: (path: string) => Promise<Response>);
+    /** Perfil de configuración de Apple Mail (plist) para el buzón de una máscara. */
+    appleProfile(domainId: string, alias: string): Promise<string>;
+    /** Exporta el buzón en formato mbox. Devuelve la respuesta en streaming: un buzón puede pesar GB. */
+    exportMbox(domainId: string, alias: string): Promise<Response>;
+    list(domainId: string): Promise<Alias[]>;
+    create(domainId: string, input: CreateAliasInput): Promise<AliasCreated>;
+    /** Crea un buzón IMAP para una máscara existente. La contraseña sólo se devuelve aquí. */
+    createMailbox(domainId: string, alias: string): Promise<MailboxCreated>;
+    /** Borra el buzón Y SU CORREO. La máscara debe conservar al menos un destino. */
+    deleteMailbox(domainId: string, alias: string): Promise<{
+        ok: boolean;
+    }>;
+    /** Genera una contraseña nueva para el buzón. Sólo se devuelve aquí; no se guarda. */
+    resetMailboxPassword(domainId: string, alias: string): Promise<{
+        password: string;
+    }>;
+    update(domainId: string, alias: string, input: UpdateAliasInput): Promise<Alias>;
+    delete(domainId: string, alias: string): Promise<{
+        ok: boolean;
+    }>;
+}
+declare class RulesResource {
+    private req;
+    constructor(req: Req);
+    list(domainId: string): Promise<Rule[]>;
+    create(domainId: string, input: CreateRuleInput): Promise<Rule>;
+    update(domainId: string, ruleId: string, input: UpdateRuleInput): Promise<Rule>;
+    delete(domainId: string, ruleId: string): Promise<{
+        ok: boolean;
+    }>;
+}
+declare class LogsResource {
+    private req;
+    constructor(req: Req);
+    /** `limit` por omisión 50, máximo 100. */
+    list(domainId: string, opts?: {
+        limit?: number;
+    }): Promise<EmailLog[]>;
+}
+declare class SendResource {
+    private req;
+    constructor(req: Req);
+    send(domainId: string, input: SendEmailInput, opts?: SendOptions): Promise<{
+        ok: boolean;
+        messageId: string;
+        sesMessageId: string;
+    }>;
+    bulkSend(domainId: string, input: BulkSendInput): Promise<BulkJobCreated>;
+    bulkStatus(domainId: string, jobId: string): Promise<BulkJob>;
+}
+declare class AttachmentsResource {
+    private req;
+    constructor(req: Req);
+    /** Máx. 5 MB. Ejecutables bloqueados (415). La llave vale hasta que se envía. */
+    upload(domainId: string, input: UploadAttachmentInput): Promise<UploadedAttachment>;
+    /** Desde un adjunto del chat del asistente (URL firmada de `/api/asistente/files/*`). */
+    uploadFromUrl(domainId: string, url: string, filename?: string): Promise<UploadedAttachment>;
+}
+declare class SuppressionsResource {
+    private req;
+    constructor(req: Req);
+    list(domainId: string): Promise<Suppression[]>;
+    add(domainId: string, email: string): Promise<Suppression>;
+    remove(domainId: string, email: string): Promise<{
+        ok: boolean;
+    }>;
+}
+declare class WebhooksResource {
+    private req;
+    constructor(req: Req);
+    list(domainId: string): Promise<Webhook[]>;
+    create(domainId: string, input: CreateWebhookInput): Promise<WebhookCreated>;
+    update(domainId: string, webhookId: string, input: UpdateWebhookInput): Promise<Webhook>;
+    delete(domainId: string, webhookId: string): Promise<{
+        ok: boolean;
+    }>;
+    /** Encola un `ping`; llega en el siguiente minuto. */
+    test(domainId: string, webhookId: string): Promise<{
+        ok: boolean;
+        deliveryId: string;
+    }>;
+    deliveries(domainId: string, webhookId: string): Promise<WebhookDelivery[]>;
+}
+declare class SmtpResource {
+    private req;
+    constructor(req: Req);
+    list(domainId: string): Promise<SmtpCredential[]>;
+    create(domainId: string, label: string): Promise<SmtpCredentialCreated>;
+    revoke(domainId: string, credId: string): Promise<{
+        ok: boolean;
+    }>;
+}
+declare class ApiKeysResource {
+    private req;
+    constructor(req: Req);
+    list(): Promise<ApiKey[]>;
+    create(name: string): Promise<ApiKey & {
+        key: string;
+    }>;
+    revoke(id: string): Promise<{
+        ok: boolean;
+    }>;
+}
+declare class BillingResource {
+    private req;
+    constructor(req: Req);
+    status(): Promise<BillingStatus>;
+    addons(): Promise<AddonsResponse>;
+    /**
+     * Liga de MercadoPago para un add-on de un dominio (`domain` = activarlo, $99/mes).
+     * El usuario la abre y paga; hasta entonces no cambia nada.
+     */
+    checkout(domainId: string, kind?: "domain" | "storage50" | "sends100", opts?: {
+        payerEmail?: string;
+        period?: "monthly" | "annual";
+    }): Promise<CheckoutLink>;
+    /** Cancela la suscripción de un add-on; el cupo sigue hasta el fin del periodo pagado. */
+    cancelAddon(addonId: string): Promise<{
+        ok: boolean;
+        activeUntil: string | null;
+    }>;
+    /** Historial de cobros, cortesías y cancelaciones (más reciente primero). */
+    orders(opts?: {
+        limit?: number;
+        before?: string;
+    }): Promise<OrdersPage>;
+}
+declare class RegistrationsResource {
+    private req;
+    constructor(req: Req);
+    search(domain: string): Promise<DomainSearchResult>;
+    tlds(): Promise<TldPrice[]>;
+    /** Crea el registro pendiente y devuelve la liga de pago; el dominio se registra al pagar. */
+    register(domain: string): Promise<DomainRegistrationCreated>;
+    list(): Promise<DomainRegistration[]>;
+    /** Pide el traslado a otro registrador. El código EPP llega por correo al dueño, nunca en la respuesta. */
+    transferOut(regId: string): Promise<{
+        ok: boolean;
+        aviso: string;
+    }>;
+    /** Liga de MercadoPago para la suscripción de renovación anual. */
+    renewal(regId: string, opts?: {
+        payerEmail?: string;
+    }): Promise<RenewalLink>;
+    /** Deja de cobrar la renovación anual. El dominio sigue vigente hasta su vencimiento. */
+    cancelRenewal(regId: string): Promise<{
+        ok: boolean;
+        aviso: string;
+    }>;
+    /**
+     * Pone el candado de transferencia. Quitarlo no está en el SDK a propósito: sólo se hace
+     * desde el panel, con la sesión del dueño y confirmando por correo.
+     */
+    lock(regId: string): Promise<{
+        ok: boolean;
+        transferLock: boolean;
+        transferUnlockedUntil: null;
+    }>;
+}
+declare class TransfersResource {
+    private req;
+    constructor(req: Req);
+    /** Requisitos, precio e inventario del DNS actual. No cobra ni crea nada. */
+    check(domain: string): Promise<TransferCheck>;
+    dns(regId: string): Promise<TransferDnsInventory>;
+    /** Reemplaza el inventario completo (RRSets). Vuelve a quedar pendiente de aprobar. */
+    setDns(regId: string, records: {
+        name: string;
+        type: string;
+        ttl?: number;
+        values: string[];
+    }[]): Promise<{
+        records: unknown[];
+    }>;
+    approveDns(regId: string): Promise<{
+        ok: boolean;
+    }>;
+    resendEmail(regId: string): Promise<{
+        ok: boolean;
+    }>;
+}
+declare class MembersResource {
+    private req;
+    constructor(req: Req);
+    list(domainId: string): Promise<{
+        members: DomainMember[];
+        invites: DomainInvite[];
+    }>;
+    invite(domainId: string, input: {
+        email: string;
+        name: string;
+        role?: "admin" | "agent";
+    }): Promise<{
+        ok: boolean;
+        inviteUrl: string;
+    }>;
+    remove(domainId: string, memberId: string): Promise<{
+        ok: boolean;
+    }>;
+    cancelInvite(domainId: string, token: string): Promise<{
+        ok: boolean;
+    }>;
+}
+declare class SignatureResource {
+    private req;
+    constructor(req: Req);
+    get(domainId: string): Promise<{
+        signature: string | null;
+    }>;
+    /** Markdown, máx. 2000 caracteres. Cadena vacía la borra. */
+    set(domainId: string, signature: string): Promise<{
+        ok: boolean;
+        signature: string | null;
+    }>;
+}
+declare class CannedResource {
+    private req;
+    constructor(req: Req);
+    list(domainId: string): Promise<CannedReply[]>;
+    create(domainId: string, input: {
+        title: string;
+        body: string;
+    }): Promise<CannedReply>;
+    delete(domainId: string, cannedId: string): Promise<{
+        ok: boolean;
+    }>;
+}
+declare class AccountResource {
+    private req;
+    constructor(req: Req);
+    /**
+     * Identidad y uso de la cuenta: dominios, derechos por dominio, add-ons y cuotas.
+     * Sustituto de `whoami` mientras no exista un endpoint de identidad más chico — ver
+     * `docs/agents/mailmask-cli.md`.
+     */
+    me(): Promise<AccountMe>;
+    /** Todo tu dato (alias, reglas y logs de cada dominio) como JSON exportable. */
+    export(): Promise<AccountExport>;
+    getProfile(): Promise<AccountProfile>;
+    /** Nombre visible (máx. 60 caracteres). Cadena vacía lo borra. */
+    updateProfile(input: {
+        displayName: string | null;
+    }): Promise<AccountProfile>;
+    /** Foto desde un adjunto que el usuario subió al asistente (URL firmada de `/api/asistente/files/*`). */
+    setAvatarFromUrl(url: string): Promise<AccountProfile & {
+        ok: boolean;
+    }>;
+    /** Foto desde bytes (PNG, JPG o WebP; máx. 2 MB). */
+    setAvatar(file: Blob, filename?: string): Promise<AccountProfile & {
+        ok: boolean;
+    }>;
+    removeAvatar(): Promise<AccountProfile & {
+        ok: boolean;
+    }>;
+}
+/**
+ * La Bandeja: conversaciones del dominio. Todo pasa por los mismos permisos que la app
+ * (dueño, admin o agente invitado) y los mismos topes de envío.
+ */
+declare class InboxResource {
+    private req;
+    private raw;
+    constructor(req: Req, raw: (path: string) => Promise<Response>);
+    list(domainId: string, opts?: InboxListOptions): Promise<InboxPage>;
+    /** Conversación con sus mensajes (los 30 más recientes, o anteriores a `before`). Abrirla la marca leída. */
+    get(domainId: string, conversationId: string, opts?: {
+        before?: string;
+    }): Promise<InboxConversationDetail>;
+    /** Un correo nuevo desde una máscara: abre un hilo. Gasta cuota de envío (dominio activado). */
+    compose(domainId: string, input: InboxComposeInput): Promise<{
+        ok: boolean;
+        conversationId: string;
+        messageId: string;
+    }>;
+    /** Responde en el hilo desde la máscara del hilo. No gasta cuota de envío. */
+    reply(domainId: string, conversationId: string, input: InboxReplyInput): Promise<{
+        ok: boolean;
+        messageId: string;
+    }>;
+    update(domainId: string, conversationId: string, input: InboxUpdateInput): Promise<InboxConversation>;
+    markRead(domainId: string, conversationId: string): Promise<{
+        ok: boolean;
+        unreadCount: number;
+    }>;
+    /** Sin `assignedTo` la deja sin asignar. */
+    assign(domainId: string, conversationId: string, assignedTo?: string): Promise<InboxConversation>;
+    /** Nota interna: la ve el equipo, nunca el contacto. */
+    addNote(domainId: string, conversationId: string, body: string): Promise<InboxNote>;
+    /** A la papelera (se puede restaurar). Máx. 200 por llamada. */
+    delete(domainId: string, conversationIds: string[]): Promise<{
+        ok: boolean;
+        deleted: number;
+    }>;
+    restore(domainId: string, conversationId: string): Promise<{
+        ok: boolean;
+    }>;
+    metrics(domainId: string, opts?: {
+        days?: number;
+    }): Promise<Record<string, unknown>>;
+    /** Bytes de un adjunto de un mensaje (id del mensaje e índice de `attachments`). */
+    attachment(domainId: string, conversationId: string, messageId: string, index: number): Promise<Response>;
+}
+declare class ReferralsResource {
+    private req;
+    constructor(req: Req);
+    get(): Promise<ReferralStats>;
+    /** 3-30 caracteres: minúsculas, números y guiones. */
+    setSlug(slug: string): Promise<{
+        ok: boolean;
+        slug: string;
+    }>;
+    /** Nombre que ven los invitados (2-40 caracteres). */
+    setName(name: string): Promise<{
+        ok: boolean;
+    }>;
+}
+export { MailMaskError };

package/dist/index.cjs

@@ -120,6 +120,22 @@ var DomainsResource = class {
   removeLogo(id) {
     return this.req(`/api/domains/${id}/logo`, { method: "DELETE" });
   }
+  /**
+   * Publica un sitio de EasyBits en el dominio: lo da de alta en EasyBits, escribe sus
+   * registros (sin tocar el correo), verifica y, en la raíz, lo asigna. Requiere la cuenta
+   * de EasyBits conectada en el navegador; sin ella, 409 con la liga para conectarla.
+   */
+  publishEasyBitsSite(id, input) {
+    return this.req(`/api/domains/${id}/website/easybits`, { method: "POST", body: JSON.stringify(input) });
+  }
+  /** Quita el sitio: el DNS vuelve a como estaba (lo que cambiaste después no se toca) y se limpia EasyBits. */
+  unpublishEasyBitsSite(id) {
+    return this.req(`/api/domains/${id}/website/easybits`, { method: "DELETE" });
+  }
+  /** Qué sitio de EasyBits está publicado en el dominio, si alguno, y si la cuenta está conectada. */
+  easyBitsSiteStatus(id) {
+    return this.req(`/api/domains/${id}/website/easybits`);
+  }
   /** Imagen para incrustar en un correo saliente (PNG, JPG, GIF o WebP; máx. 2 MB). Efímera: se borra tras enviarse o por el barrido diario. */
   uploadImage(id, file, filename = "imagen") {
     const form = new FormData();
@@ -150,8 +166,17 @@ var DnsResource = class {
   delete(domainId, name, type) {
     return this.req(`/api/domains/${domainId}/dns/records`, { method: "DELETE", body: JSON.stringify({ name, type }) });
   }
-  preset(domainId, preset, target, subdomain) {
-    return this.req(`/api/domains/${domainId}/dns/preset`, { method: "POST", body: JSON.stringify({ preset, target, subdomain }) });
+  /** Con 'easybits' publica un sitio de la cuenta conectada (`opts.websiteId`), igual que `domains.publishEasyBitsSite`. */
+  preset(domainId, preset, target, subdomain, opts) {
+    return this.req(`/api/domains/${domainId}/dns/preset`, { method: "POST", body: JSON.stringify({ preset, target, subdomain, ...opts }) });
+  }
+  /** Vista previa de una plantilla: lo que escribiría y lo que hay hoy, sin tocar nada. */
+  presetPreview(domainId, preset, target, subdomain, opts) {
+    return this.req(`/api/domains/${domainId}/dns/preset`, { method: "POST", body: JSON.stringify({ preset, target, subdomain, ...opts, dryRun: true }) });
+  }
+  /** A dónde apunta el sitio (raíz, www y subdominios), qué plataforma es, qué está mal y si responde por HTTPS. */
+  website(domainId) {
+    return this.req(`/api/domains/${domainId}/website`);
   }
 };
 var AliasesResource = class {