Caramel SDK
Un SDK de TypeScript para crear, perfeccionar y desplegar campañas y plantillas de Caramel desde tu propio código — las mismas operaciones que tu equipo hace a mano en la aplicación Caramel, ahora invocables desde un script. Sin dependencias en tiempo de ejecución, basado en fetch nativo.
Pre-1.0 — todavía no está en el registro público de npm
El propio README de @caramel/sdk lo dice claramente: la superficie de la API y el modelo de autenticación todavía están cambiando. Solicita acceso y compartiremos el paquete y la documentación actual directamente con tu espacio de trabajo.
Una vez que tu espacio de trabajo tenga acceso:
Node.js 18 o superior. La URL base por defecto es api.caramelme.com.
npm install @caramel/sdk - Tres formas de autenticarte:
-
CaramelSDK.fromCredentials({ email, password }) — inicia sesión directamente -
new CaramelSDK({ accessToken, refreshToken? }) — reutiliza un token de sesión existente -
CaramelSDK.fromIngestKey('ck_live_…') — limitado solo al módulo customers
Inicia sesión, busca una empresa y genera un borrador de campaña:
import { CaramelSDK } from '@caramel/sdk';
const caramel = await CaramelSDK.fromCredentials({
email: process.env.CARAMEL_EMAIL!,
password: process.env.CARAMEL_PASSWORD!,
});
const [business] = await caramel.businesses.list();
const draft = await caramel.campaigns.generate({
businessId: business.id,
prompt: 'Win back customers who have not ordered in 60 days. Warm, not pushy.',
});
console.log(draft.id, draft.validationStatus, draft.evaluationScores?.overall); Qué puedes llamar
Cuatro módulos, correspondientes a lo que realmente está implementado y publicado en el paquete hoy.
| Módulo | Métodos | Notas |
|---|---|---|
| businesses | list() | Lista las empresas a las que tus credenciales pueden acceder. |
| campaigns | list()get()generate()refine()deploy()pause()resume()delete()suggest() | Genera, perfecciona, versiona, programa y gestiona todo el ciclo de vida de un borrador de campaña. |
| templates | list()deploy() | Lista la biblioteca de plantillas y despliega una como punto de partida. |
| customers | identify()identifyBatch()track()purchase()trackBatch()unmap()forget() | Incluido en el paquete. Los endpoints del backend todavía no están activos en producción — no construyas todavía sobre este módulo. |
Qué puedes construir
El SDK no añade capacidades nuevas respecto a la app Caramel — añade automatización. Así es en la práctica.
Campañas programadas desde tus propios disparadores
Integra generate_campaign y deploy() en un cron job, un pipeline de datos o una herramienta interna. Redacta una campaña de recuperación cada lunes sin abrir la app Caramel.
Herramientas internas para perfiles no marketing
Construye un panel ligero o un comando de Slack que llame a campaigns.suggest() y campaigns.generate(), para que cualquiera del equipo pueda crear un borrador sin aprender la interfaz de Caramel.
Despliegue de plantillas en varios espacios de trabajo
Si gestionas más de una empresa en Caramel — agencias, franquicias — recorre businesses.list() y despliega una plantilla con templates.deploy() en lugar de repetir la configuración manual por cuenta.
Tu propio flujo de revisión
Cada respuesta de generate_campaign incluye validationStatus y evaluationScores. Construye tu propia cola de aprobación o notificación de Slack sobre eso, en lugar de depender de la pantalla de revisión de la app Caramel.
Casos de uso
Formas realistas en las que los equipos usan el SDK, basadas en lo que la API realmente hace.
Campañas de recuperación programadas
Un equipo de crecimiento integra generate_campaign en un cron job semanal que redacta una campaña de recuperación para clientes inactivos 60 días o más, y publica el borrador en Slack para que una persona lo revise y despliegue.
Herramientas de agencia multi-espacio
Una agencia que gestiona una docena de espacios de trabajo de Caramel construye una herramienta interna que recorre businesses.list() y genera un borrador de campaña mensual para cada cliente desde un único script, en lugar de entrar a cada espacio manualmente.
Revisión de campañas integrada en CI
Un equipo añade un paso a su propio proceso de revisión que llama a refine_campaign contra una guía de estilo antes de aprobar un borrador para su envío, detectando problemas de tono o cumplimiento antes de que los vea una persona.
Estandarización de plantillas a gran escala
Un responsable de operaciones usa templates.deploy() en un script para desplegar una plantilla estacional actualizada en cada empresa de su cartera en una sola ejecución, en lugar de repetir los mismos pasos por espacio de trabajo.
Gestión de errores
Cada fallo lanza un CaramelError con un .code identificable por código:
AUTH_FAILEDUNAUTHORIZEDINSUFFICIENT_CREDITSTIER_UPGRADE_REQUIREDCAMPAIGN_DEPLOYEDVALIDATION_FAILEDNOT_FOUNDSERVER_ERRORNETWORK_ERRORCONFLICTCUSTOMER_SUPPRESSEDRATE_LIMITEDPAYLOAD_TOO_LARGE Preguntas antes de empezar
¿@caramel/sdk está en npm?
Todavía no. El paquete no está publicado en el registro público de npm. Solicita acceso y compartiremos directamente el paquete y las instrucciones de instalación actuales.
¿Es estable el SDK?
No — está en pre-1.0. El propio README del SDK indica que la superficie de la API y el modelo de autenticación todavía están cambiando. Espera cambios importantes antes de una versión 1.0.
¿Puedo usar el módulo customers?
Todavía no en producción. Está incluido en el código del paquete, pero sus endpoints de backend devuelven actualmente un error 404. Todo lo relacionado con businesses, campaigns y templates está activo.
¿Qué puedo construir con el SDK que no pueda hacer en la app Caramel?
Nada nuevo en cuanto a capacidad — el SDK llama a las mismas operaciones disponibles en la app. Lo que añade es automatización: dispararlas desde tu propio calendario, pipeline o herramienta interna en lugar de que una persona haga clic en la interfaz.
¿El SDK admite uso en servidor y en cliente?
Está pensado para uso en servidor — los flujos de credenciales y de clave de ingesta asumen un entorno de confianza. Se distribuye en compilaciones ESM y CommonJS con los tipos de TypeScript incluidos.
Empieza con un espacio de trabajo en Caramel
El acceso al SDK se concede por espacio de trabajo. Crea el tuyo y solicita acceso: te compartiremos el paquete y la documentación actual.
Empezar