Caramel SDK
Un SDK TypeScript pour créer, affiner et déployer des campagnes et des modèles Caramel depuis votre propre code — les mêmes opérations que votre équipe effectue manuellement dans l'application Caramel, appelables depuis un script. Aucune dépendance à l'exécution, basé sur fetch natif.
Pré-1.0 — pas encore sur le registre npm public
Le README de @caramel/sdk le dit clairement : la surface de l'API et le modèle d'authentification évoluent encore. Demandez l'accès et nous partagerons le package et la documentation actuelle directement avec votre espace de travail.
Une fois l'accès accordé à votre espace de travail :
Node.js 18 ou supérieur. L'URL de base par défaut est api.caramelme.com.
npm install @caramel/sdk - Trois façons de s'authentifier :
-
CaramelSDK.fromCredentials({ email, password }) — connexion directe -
new CaramelSDK({ accessToken, refreshToken? }) — réutiliser un jeton de session existant -
CaramelSDK.fromIngestKey('ck_live_…') — limité au module customers uniquement
Connectez-vous, trouvez une entreprise et générez un brouillon de campagne :
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); Ce que vous pouvez appeler
Quatre modules, correspondant à ce qui est réellement implémenté et livré dans le package aujourd'hui.
| Module | Méthodes | Remarques |
|---|---|---|
| businesses | list() | Liste les entreprises accessibles avec vos identifiants. |
| campaigns | list()get()generate()refine()deploy()pause()resume()delete()suggest() | Génère, affine, versionne, planifie et gère l'intégralité du cycle de vie d'un brouillon de campagne. |
| templates | list()deploy() | Liste la bibliothèque de modèles et déploie un modèle comme point de départ. |
| customers | identify()identifyBatch()track()purchase()trackBatch()unmap()forget() | Livré dans le package. Les points d'accès backend ne sont pas encore actifs en production — n'utilisez pas ce module pour l'instant. |
Ce que vous pouvez construire
Le SDK n'ajoute pas de nouvelles capacités par rapport à l'application Caramel — il ajoute l'automatisation. Voici à quoi cela ressemble en pratique.
Campagnes planifiées depuis vos propres déclencheurs
Intégrez generate_campaign et deploy() dans une tâche cron, un pipeline de données ou un outil interne. Rédigez une campagne de réactivation chaque lundi sans ouvrir l'application Caramel.
Outils internes pour les non-marketeurs
Construisez un tableau de bord léger ou une commande Slack qui appelle campaigns.suggest() et campaigns.generate(), pour que n'importe qui dans l'équipe puisse créer un brouillon sans apprendre l'interface Caramel.
Déploiement de modèles sur plusieurs espaces de travail
Si vous gérez plusieurs entreprises Caramel — agences, franchises — parcourez businesses.list() et poussez un modèle avec templates.deploy() au lieu de répéter la configuration manuelle par compte.
Votre propre flux de validation
Chaque réponse de generate_campaign inclut validationStatus et evaluationScores. Construisez votre propre file d'approbation ou notification Slack par-dessus, au lieu de dépendre de l'écran de révision de l'application Caramel.
Cas d'usage
Des façons concrètes d'utiliser le SDK, construites à partir de ce que l'API fait réellement.
Campagnes de réactivation planifiées
Une équipe croissance intègre generate_campaign dans une tâche cron hebdomadaire qui rédige une campagne de réactivation pour les clients inactifs depuis 60 jours ou plus, puis publie le brouillon sur Slack pour qu'une personne le révise et le déploie.
Outillage d'agence multi-espaces
Une agence gérant une douzaine d'espaces de travail Caramel construit un outil interne qui parcourt businesses.list() et génère un brouillon de campagne mensuel pour chaque client depuis un seul script, au lieu de se connecter à chaque espace manuellement.
Révision de campagne intégrée en CI
Une équipe ajoute une étape à son propre processus de révision qui appelle refine_campaign par rapport à un guide de style avant qu'un brouillon soit approuvé pour l'envoi, détectant les problèmes de ton ou de conformité avant qu'une personne ne les voie.
Standardisation des modèles à grande échelle
Un responsable opérations utilise templates.deploy() dans un script pour déployer un modèle saisonnier mis à jour sur chaque entreprise de son portefeuille en une seule exécution, au lieu de répéter les mêmes étapes par espace de travail.
Gestion des erreurs
Chaque échec lève un CaramelError avec un .code exploitable par un programme :
AUTH_FAILEDUNAUTHORIZEDINSUFFICIENT_CREDITSTIER_UPGRADE_REQUIREDCAMPAIGN_DEPLOYEDVALIDATION_FAILEDNOT_FOUNDSERVER_ERRORNETWORK_ERRORCONFLICTCUSTOMER_SUPPRESSEDRATE_LIMITEDPAYLOAD_TOO_LARGE Questions avant de commencer
@caramel/sdk est-il sur npm ?
Pas encore. Le package n'est pas publié sur le registre npm public. Demandez l'accès et nous partagerons directement le package et les instructions d'installation actuelles.
Le SDK est-il stable ?
Non — il est en pré-1.0. Le README du SDK indique que la surface de l'API et le modèle d'authentification évoluent encore. Attendez-vous à des changements majeurs avant une version 1.0.
Puis-je utiliser le module customers ?
Pas encore en production. Il est livré dans le code du package, mais ses points d'accès backend renvoient actuellement une erreur 404. Tout ce qui concerne businesses, campaigns et templates est actif.
Que puis-je construire avec le SDK que je ne peux pas faire dans l'application Caramel ?
Rien de nouveau en termes de capacités — le SDK appelle les mêmes opérations disponibles dans l'application. Ce qu'il ajoute, c'est l'automatisation : les déclencher depuis votre propre planning, pipeline ou outil interne au lieu qu'une personne clique dans l'interface.
Le SDK prend-il en charge une utilisation côté serveur et côté client ?
Il est conçu pour une utilisation côté serveur — les flux d'identifiants et de clé d'ingestion supposent un environnement de confiance. Il est livré en ESM et CommonJS avec les types TypeScript inclus.
Commencez avec un espace de travail Caramel
L'accès au SDK est accordé par espace de travail. Créez le vôtre, puis demandez l'accès : nous vous partagerons le paquet et la documentation à jour.
Commencer