Caramel SDK
Un SDK TypeScript per creare, perfezionare e distribuire campagne e template Caramel dal tuo codice — le stesse operazioni che il tuo team esegue manualmente nell'app Caramel, ora richiamabili da uno script. Nessuna dipendenza a runtime, basato su fetch nativo.
Pre-1.0 — non ancora sul registro pubblico npm
Il README di @caramel/sdk lo dice chiaramente: la superficie dell'API e il modello di autenticazione sono ancora in evoluzione. Richiedi l'accesso e condivideremo il pacchetto e la documentazione attuale direttamente con il tuo workspace.
Una volta che il tuo workspace ha accesso:
Node.js 18 o successivo. L'URL di base predefinito è api.caramelme.com.
npm install @caramel/sdk - Tre modi per autenticarti:
-
CaramelSDK.fromCredentials({ email, password }) — accedi direttamente -
new CaramelSDK({ accessToken, refreshToken? }) — riusa un token di sessione esistente -
CaramelSDK.fromIngestKey('ck_live_…') — limitato al solo modulo customers
Accedi, trova un'azienda e genera una bozza di campagna:
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); Cosa puoi richiamare
Quattro moduli, corrispondenti a ciò che è realmente implementato e distribuito nel pacchetto oggi.
| Modulo | Metodi | Note |
|---|---|---|
| businesses | list() | Elenca le aziende a cui le tue credenziali possono accedere. |
| campaigns | list()get()generate()refine()deploy()pause()resume()delete()suggest() | Genera, perfeziona, versiona, pianifica e gestisce l'intero ciclo di vita di una bozza di campagna. |
| templates | list()deploy() | Elenca la libreria dei template e distribuisce un template come punto di partenza. |
| customers | identify()identifyBatch()track()purchase()trackBatch()unmap()forget() | Incluso nel pacchetto. Gli endpoint backend non sono ancora attivi in produzione — non basarti ancora su questo modulo. |
Cosa puoi costruire
L'SDK non aggiunge nuove funzionalità rispetto all'app Caramel — aggiunge automazione. Ecco come si traduce nella pratica.
Campagne programmate dai tuoi trigger
Integra generate_campaign e deploy() in un cron job, una pipeline dati o uno strumento interno. Crea una campagna di riattivazione ogni lunedì senza aprire l'app Caramel.
Strumenti interni per chi non fa marketing
Costruisci una dashboard leggera o un comando Slack che richiama campaigns.suggest() e campaigns.generate(), così chiunque nel team può creare una bozza senza imparare l'interfaccia Caramel.
Distribuzione di template su più workspace
Se gestisci più aziende Caramel — agenzie, franchising — scorri businesses.list() e distribuisci un template con templates.deploy() invece di ripetere la configurazione manuale per ogni account.
Il tuo flusso di revisione
Ogni risposta di generate_campaign include validationStatus e evaluationScores. Costruisci la tua coda di approvazione o notifica Slack su questi dati, invece di affidarti alla schermata di revisione dell'app Caramel.
Casi d'uso
Modi realistici in cui i team usano l'SDK, basati su ciò che l'API fa davvero.
Campagne di riattivazione programmate
Un team growth integra generate_campaign in un cron job settimanale che crea una campagna di riattivazione per i clienti inattivi da 60 o più giorni, poi pubblica la bozza su Slack perché una persona la riveda e la distribuisca.
Strumenti per agenzie multi-workspace
Un'agenzia che gestisce una dozzina di workspace Caramel costruisce uno strumento interno che scorre businesses.list() e genera una bozza di campagna mensile per ogni cliente da un unico script, invece di accedere manualmente a ogni workspace.
Revisione delle campagne integrata in CI
Un team aggiunge un passaggio al proprio processo di revisione che richiama refine_campaign rispetto a una guida di stile prima che una bozza venga approvata per l'invio, individuando problemi di tono o conformità prima che li veda una persona.
Standardizzazione dei template su larga scala
Un responsabile operations usa templates.deploy() in uno script per distribuire un template stagionale aggiornato su ogni azienda del portfolio in un'unica esecuzione, invece di ripetere gli stessi passaggi per ogni workspace.
Gestione degli errori
Ogni errore genera un CaramelError con un .code leggibile da un programma:
AUTH_FAILEDUNAUTHORIZEDINSUFFICIENT_CREDITSTIER_UPGRADE_REQUIREDCAMPAIGN_DEPLOYEDVALIDATION_FAILEDNOT_FOUNDSERVER_ERRORNETWORK_ERRORCONFLICTCUSTOMER_SUPPRESSEDRATE_LIMITEDPAYLOAD_TOO_LARGE Domande prima di iniziare
@caramel/sdk è su npm?
Non ancora. Il pacchetto non è pubblicato sul registro pubblico npm. Richiedi l'accesso e condivideremo direttamente il pacchetto e le istruzioni di installazione attuali.
L'SDK è stabile?
No — è pre-1.0. Il README dell'SDK indica che la superficie dell'API e il modello di autenticazione sono ancora in evoluzione. Aspettati cambiamenti importanti prima di una versione 1.0.
Posso usare il modulo customers?
Non ancora in produzione. È incluso nel codice del pacchetto, ma i suoi endpoint backend al momento restituiscono un errore 404. Tutto ciò che riguarda businesses, campaigns e templates è attivo.
Cosa posso costruire con l'SDK che non posso fare nell'app Caramel?
Niente di nuovo in termini di capacità — l'SDK richiama le stesse operazioni disponibili nell'app. Ciò che aggiunge è l'automazione: attivarle dal tuo programma, dalla tua pipeline o dal tuo strumento interno invece che con un clic nell'interfaccia da parte di una persona.
L'SDK supporta l'uso lato server e lato client?
È pensato per l'uso lato server — i flussi di credenziali e di chiave di ingest presuppongono un ambiente affidabile. Viene distribuito in build ESM e CommonJS con i tipi TypeScript inclusi.
Inizia con un workspace Caramel
L'accesso all'SDK viene concesso per workspace. Crea il tuo, poi richiedi l'accesso e condivideremo il pacchetto e la documentazione aggiornata.
Inizia