SDK de Node v4: TypeScript-first con soporte integral de Robots

Kevin van Zonneveld

Cofundador · Ámsterdam, Países Bajos · Mostrar bio

Hoy lanzamos la versión 4 de nuestro SDK de Node.js, el replanteamiento más grande del paquete desde su lanzamiento inicial. Ahora puedes contar con una cobertura integral de TypeScript, definiciones completas de Robots con autocompletado, manejo estructurado de errores y herramientas modernas, todo ello respetando los quince años de recorrido de una API que ha crecido junto con el ecosistema de Node.

Novedades de la v4

El SDK de Node v4 representa una reescritura completa en TypeScript con estas mejoras principales:

Diseño que prioriza TypeScript

Cada Robot, parámetro y respuesta ahora está completamente tipado. Cuando escribes Assembly Instructions, tu IDE te sugiere los Robots, los parámetros y los valores de retorno correctos a medida que escribes:

import { Transloadit } from 'transloadit'

const transloadit = new Transloadit({
  authKey: process.env.TRANSLOADIT_KEY,
  authSecret: process.env.TRANSLOADIT_SECRET,
})

await transloadit.createAssembly({
  params: {
    steps: {
      resize: {
        use: ':original',
        robot: '/image/resize', // ← autocompletes all available Robots
        width: 320, // ← only shows valid parameters for this Robot
        height: 240,
        result: true,
      },
    },
  },
  waitForCompletion: true,
})

Las Assembly Instructions se validan contra tipos detallados, de modo que los problemas de configuración o de compatibilidad hacia atrás se detectan pronto, durante el desarrollo local, en lugar de a mitad del despliegue.

Entorno moderno de JavaScript

El SDK ahora es puramente ESM y apunta a Node.js 20+, usando exportaciones nombradas en toda su API:

// Named exports replace the default export
import { Transloadit } from 'transloadit'

Para proyectos CommonJS, usa importaciones dinámicas:

async function getClient() {
  const { Transloadit } = await import('transloadit')
  return new Transloadit({ authKey, authSecret })
}

Mejor manejo de errores

Nuestros errores ahora incluyen trazas de pila detalladas con más contexto para depurar más fácilmente.

Función auxiliar de URL de Smart CDN

Genera URL firmadas de Smart CDN directamente desde el SDK:

const signedUrl = transloadit.getSignedSmartCDNUrl({
  workspace: 'my-team',
  template: 'hero-image',
  input: 'photo.jpg',
  urlParams: { format: 'webp' },
})

Nuestro enfoque para incorporar tipos

Al agregar TypeScript a una API que ha evolucionado de forma orgánica durante quince años, nos enfrentamos a un reto interesante. Nuestra API nació en los primeros días de Node.js, cuando JavaScript era mucho más permisivo, en una época en la que el tipado dinámico era la norma.

En lugar de crear definiciones de tipos idealizadas que romperían las integraciones existentes, optamos por un enfoque pragmático:

1. Modelar lo que existe: nuestros tipos reflejan con precisión la superficie actual de la API, incluso cuando eso implica aceptar patrones que no son perfectos.

2. Probarlo todo: cada definición de tipo pasa por nuestro banco de pruebas para asegurar que coincida con el comportamiento real de la API.

3. Iterar hacia la belleza: con tipos precisos como base, podemos refinar gradualmente tanto los esquemas como la propia API, garantizando siempre la compatibilidad hacia atrás.

4. Preservar la compatibilidad: cuando la API tiene peculiaridades, las documentamos en lugar de forzar cambios inmediatos.

Este enfoque implica que, al principio, nuestros tipos quizá no ganen concursos de belleza. Puede que veas uniones donde esperarías un solo tipo, o campos opcionales que lógicamente deberían ser obligatorios. Esto es intencional: estamos capturando quince años de evolución de la API, durante los cuales distintos endpoints surgieron en momentos distintos y con convenciones distintas.

Al adoptar este enfoque prudente, nos aseguramos de que el código existente siga funcionando, de que el código nuevo reciba la orientación adecuada y de que las mejoras futuras sigan siendo posibles. Creemos que quienes desarrollan software valoran la honestidad por encima del idealismo. Nuestros tipos dicen la verdad sobre nuestra API, con peculiaridades y todo.

Guía de migración

Pasar de la v3 a la v4 requiere algunos cambios clave:

Lista rápida de comprobación para actualizar

1. Actualiza a transloadit@^4.0.0 y asegúrate de estar en Node.js 20 o una versión más reciente
2. Cambia las importaciones por defecto por importaciones nombradas
3. Elimina las llamadas require de CommonJS (usa importaciones dinámicas en su lugar)
4. Habilita TypeScript o agrega tipados JSDoc para un mejor soporte en el editor
5. Actualiza el manejo de errores si usas clases de error personalizadas
6. Ejecuta tus pruebas de integración con validateResponses habilitado para detectar sorpresas en los esquemas. Por favor, avísanos si obtienes algún error y lo solucionaremos.

Validación de respuestas (opcional)

Habilita la validación en tiempo de ejecución de las respuestas de la API durante el desarrollo:

const transloadit = new Transloadit({
  authKey,
  authSecret,
  validateResponses: true, // This runs API responses through Zod, so you can have more confidence in the types. This will become the default in 5.x, but for this release it still defaults to false
})

Mejoras en la experiencia de desarrollo

El nuevo SDK se integra sin fricciones con los flujos de trabajo modernos:

• Soporte completo de IntelliSense en VS Code y otros IDE
• Comentarios JSDoc detallados para todos los métodos y parámetros
• Mapas de origen para depurar más fácilmente
• Compatibilidad con la comprobación estricta de nulos

Primeros pasos

Instala el nuevo SDK:

npm install transloadit@^4.0.0

Crea un cliente y empieza a construir:

import { Transloadit } from 'transloadit'

const transloadit = new Transloadit({
  authKey: 'YOUR_AUTH_KEY',
  authSecret: 'YOUR_AUTH_SECRET',
})

// TypeScript knows exactly what's available
const assembly = await transloadit.createAssembly({
  params: {
    steps: {
      optimize: {
        use: ':original',
        robot: '/image/optimize',
      },
    },
  },
})

¿Qué sigue?

Este lanzamiento de la v4 es solo el comienzo de nuestro camino con TypeScript. A medida que sigamos refinando nuestra API y nuestros esquemas, verás tipos aún más precisos, mejor documentación generada a partir de las definiciones de tipos, mensajes de error mejorados y refinamientos graduales de los esquemas que mantienen la compatibilidad.

Pruébalo hoy

El SDK de Node v4 ya está disponible en npm⁠ y GitHub⁠. Consulta la guía de migración⁠ para ver instrucciones detalladas de actualización, ¡y cuéntanos qué te parece!

¿Listo para empezar? Crea una cuenta gratuita y prueba por ti mismo el nuevo SDK impulsado por TypeScript.

Actualización del 2 de febrero de 2026: ahora también ofrecemos @transloadit/zod/v3, @transloadit/zod/v4, @transloadit/types por si necesitas nuestros esquemas o tipos sin incorporar el SDK completo de Node.js. Además, se ha renombrado a @transloadit/node, mientras que transloadit seguirá disponible como un clon de este, por compatibilidad hacia atrás.