SDK de TypeScript

Si tu equipo trabaja con JavaScript o TypeScript, el SDK es la forma más rápida de conectar una aplicación a freedam. En lugar de escribir tú mismo toda la parte técnica de bajo nivel de una integración con una API (solicitudes, reintentos, recorrer listas largas, esperar a que terminen los trabajos), instalas un solo paquete y cada parte de la biblioteca queda a una simple llamada de método.

Qué hace

@freedam/sdk es el cliente oficial de la API REST de freedam. Funciona en todos los entornos habituales de JavaScript (Node, Bun, Deno y el navegador) y se genera directamente a partir de la descripción publicada de la propia API, así que siempre coincide con lo que la API hace realmente.

Todo lo que hay en la biblioteca está en el cliente: recursos, colecciones, importaciones, enlaces para compartir, operaciones en segundo plano, metadatos, webhooks y más. Como el cliente está completamente tipado, tu editor autocompleta las llamadas disponibles y señala un nombre de campo incorrecto mientras escribes, antes de que se ejecute nada.

import { FreedamClient } from '@freedam/sdk';

const client = new FreedamClient({
    baseUrl: 'https://your-instance.example.com',
    token: process.env.FREEDAM_TOKEN!,
});

const { data } = await client.assets.list({ per_page: 50 });

Cómo funciona

Además de cubrir todos los endpoints, el SDK se encarga de las tareas que, si no, tendrías que escribir tú:

• Paginación sin esfuerzo. Obtén una página, recorre las páginas a medida que las necesites u obtén todo con una sola llamada.
• Importaciones como flujo. Inicia un lote, envía tus archivos y sigue el avance hasta que cada archivo esté totalmente procesado.
• Trabajos en segundo plano. Inicia una actualización en bloque o una exportación y simplemente espera: el SDK consulta el avance por ti hasta que el trabajo termina.
• Seguridad de los webhooks. Una sola llamada verifica que una notificación de webhook entrante provenga realmente de tu instancia de freedam.
• Reintentos automáticos. Los fallos temporales de red y los errores del servidor se reintentan por ti, y el cliente reduce el ritmo automáticamente cuando se le pide, de modo que respeta los límites de velocidad de la API sin código adicional.

Cuando algo sale mal, los errores son claros y específicos: el SDK te indica si no se encontró un recurso, si una solicitud superó el límite de velocidad o si una firma no se pudo verificar, para que tu código reaccione a cada caso con limpieza.

Conviene saber

• El acceso funciona igual que en el resto del producto: creas un token de API en Ajustes → Tokens de API con exactamente los permisos que necesita tu integración. El SDK no añade accesos laterales; un token que no puede editar recursos tampoco puede editarlos mediante el SDK.
• El SDK es joven. Las versiones anteriores a la 1.0 pueden cambiar ocasionalmente el nombre de algunos elementos: fija tu versión y lee el registro de cambios incluido en el paquete (CHANGELOG.md) antes de actualizar. La API en sí se mantiene estable de forma independiente.
• ¿No trabajas con TypeScript? La descripción publicada de la API funciona con herramientas estándar para generar un cliente en la mayoría de los demás lenguajes.

La referencia completa de métodos y los patrones de uso están en la documentación de la API. ¿Quieres una instancia en vivo a la que apuntar el cliente mientras construyes? Prueba la demostración.