Diseño de SDK clients

El SDK mx que usas en los playgrounds sigue patrones deliberados. Un buen cliente esconde HTTP, firma, reintentos y paginación detrás de una superficie pequeña y predecible.

Principios

• Recursos como namespaces: sms, chat, otp, webhook.
• Errores tipados: RateLimitError con retryAfter, ValidationError con el campo.
• Defaults seguros: timeouts, reintentos idempotentes, TLS obligatorio.
• Sin estado global: varias instancias con credenciales distintas deben convivir.

export class MessagingClient {
  constructor({ apiKey, baseUrl = "https://api.example.com", timeoutMs = 10000 }) {
    this.http = createHttp({ apiKey, baseUrl, timeoutMs });
    this.sms = { send: (input) => this.http.post("/v1/sms", validateSms(input)) };
  }
}

Un buen SDK no es una envoltura delgada sobre HTTP: es una interfaz que hace fácil lo correcto. Debe validar entradas antes de salir a la red, aplicar reintentos seguros por defecto, exponer errores tipados y nunca registrar secretos en sus logs.

Diseña la superficie pública pensando en el código que escribirá tu usuario. mx.sms.send({ to, text }) se lee como una frase; un método con siete argumentos posicionales obliga a consultar la documentación en cada uso.

Principios que sostienen un SDK

• Objetos de opciones en lugar de argumentos posicionales: permiten agregar campos sin romper compatibilidad.
• Errores tipados (ValidationError, RateLimitError) para que el llamador decida si reintentar.
• Timeouts explícitos con valores por defecto razonables.
• Versionado semántico estricto y changelog legible.

Cuando dudes entre agregar una opción o no, recuerda que cada opción pública es una promesa que deberás mantener durante años.