Caramel SDK

Ein TypeScript-SDK zum Erstellen, Verfeinern und Bereitstellen von Caramel-Kampagnen und Vorlagen aus Ihrem eigenen Code — dieselben Vorgänge, die Ihr Team manuell in der Caramel-App ausführt, jetzt aus einem Skript aufrufbar. Keine Laufzeitabhängigkeiten, basiert auf nativem fetch.

Pre-1.0 — noch nicht im öffentlichen npm-Registry

Das README von @caramel/sdk sagt es klar: Die API-Oberfläche und das Authentifizierungsmodell befinden sich noch in Bewegung. Fragen Sie Zugang an, und wir teilen das Paket sowie die aktuelle Dokumentation direkt mit Ihrem Workspace.

Sobald Ihr Workspace Zugang hat:

Node.js 18 oder neuer. Die Standard-Basis-URL ist api.caramelme.com.

npm install @caramel/sdk
  • Drei Wege zur Authentifizierung:
  • CaramelSDK.fromCredentials({ email, password }) — direkte Anmeldung
  • new CaramelSDK({ accessToken, refreshToken? }) — ein bestehendes Sitzungstoken wiederverwenden
  • CaramelSDK.fromIngestKey('ck_live_…') — beschränkt auf das customers-Modul

Anmelden, ein Unternehmen finden und einen Kampagnenentwurf generieren:

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);

Was Sie aufrufen können

Vier Module, passend zu dem, was im Paket heute tatsächlich implementiert und ausgeliefert ist.

Modul Methoden Hinweise
businesses
list()
Listet die Unternehmen, auf die Ihre Zugangsdaten zugreifen können.
campaigns
list()get()generate()refine()deploy()pause()resume()delete()suggest()
Generiert, verfeinert, versioniert, plant und verwaltet den gesamten Lebenszyklus eines Kampagnenentwurfs.
templates
list()deploy()
Listet die Vorlagenbibliothek und stellt eine Vorlage als Ausgangspunkt bereit.
customers
identify()identifyBatch()track()purchase()trackBatch()unmap()forget()
Im Paket enthalten. Die Backend-Endpunkte sind in der Produktion noch nicht aktiv — bauen Sie noch nicht auf diesem Modul auf.

Was Sie bauen können

Das SDK fügt keine neuen Fähigkeiten gegenüber der Caramel-App hinzu — es fügt Automatisierung hinzu. So sieht das in der Praxis aus.

Geplante Kampagnen aus eigenen Auslösern

Binden Sie generate_campaign und deploy() in einen Cron-Job, eine Datenpipeline oder ein internes Tool ein. Entwerfen Sie jeden Montag eine Rückgewinnungskampagne, ohne die Caramel-App zu öffnen.

Interne Tools für Nicht-Marketer

Bauen Sie ein schlankes Dashboard oder einen Slack-Befehl, der campaigns.suggest() und campaigns.generate() aufruft, damit jeder im Team einen Entwurf erstellen kann, ohne die Caramel-Oberfläche zu lernen.

Vorlagen-Rollout über mehrere Workspaces

Wenn Sie mehr als ein Caramel-Unternehmen betreiben – Agenturen, Franchises –, durchlaufen Sie businesses.list() und spielen eine Vorlage mit templates.deploy() aus, statt die manuelle Einrichtung pro Konto zu wiederholen.

Ihr eigener Prüfworkflow

Jede generate_campaign-Antwort enthält validationStatus und evaluationScores. Bauen Sie darauf Ihre eigene Freigabe-Warteschlange oder Slack-Benachrichtigung, statt sich auf den Prüfbildschirm der Caramel-App zu verlassen.

Anwendungsfälle

Realistische Wege, wie Teams das SDK einsetzen, basierend auf dem, was die API tatsächlich tut.

Geplante Rückgewinnungskampagnen

Ein Growth-Team bindet generate_campaign in einen wöchentlichen Cron-Job ein, der eine Rückgewinnungskampagne für seit 60+ Tagen inaktive Kunden entwirft und den Entwurf dann zur Prüfung und Bereitstellung in Slack postet.

Agentur-Tooling für mehrere Workspaces

Eine Agentur, die ein Dutzend Caramel-Workspaces verwaltet, baut ein internes Tool, das businesses.list() durchläuft und aus einem einzigen Skript einen monatlichen Kampagnenentwurf für jeden Kunden erzeugt, statt sich manuell in jeden Workspace einzuloggen.

CI-gestützte Kampagnenprüfung

Ein Team fügt seinem eigenen Prüfprozess einen Schritt hinzu, der refine_campaign gegen einen Styleguide aufruft, bevor ein Entwurf zum Versand freigegeben wird, und erkennt so Ton- oder Compliance-Probleme, bevor sie ein Mensch sieht.

Vorlagen-Standardisierung im großen Maßstab

Ein Operations-Verantwortlicher nutzt templates.deploy() in einem Skript, um eine aktualisierte Saisonvorlage in einem Durchlauf auf jedes Unternehmen im Portfolio auszuspielen, statt die Schritte pro Workspace zu wiederholen.

Fehlerbehandlung

Jeder Fehlschlag wirft einen CaramelError mit einem maschinenlesbaren .code:

AUTH_FAILEDUNAUTHORIZEDINSUFFICIENT_CREDITSTIER_UPGRADE_REQUIREDCAMPAIGN_DEPLOYEDVALIDATION_FAILEDNOT_FOUNDSERVER_ERRORNETWORK_ERRORCONFLICTCUSTOMER_SUPPRESSEDRATE_LIMITEDPAYLOAD_TOO_LARGE

Fragen vor dem Start

Ist @caramel/sdk auf npm?

Noch nicht. Das Paket ist nicht im öffentlichen npm-Registry veröffentlicht. Fragen Sie Zugang an, und wir teilen das Paket sowie die aktuelle Installationsanleitung direkt mit Ihnen.

Ist das SDK stabil?

Nein — es ist pre-1.0. Das README des SDK besagt, dass die API-Oberfläche und das Authentifizierungsmodell sich noch ändern. Rechnen Sie vor einer 1.0-Version mit Breaking Changes.

Kann ich das customers-Modul nutzen?

Noch nicht in der Produktion. Es ist im Code des Pakets enthalten, aber seine Backend-Endpunkte liefern derzeit einen 404-Fehler. Alles unter businesses, campaigns und templates ist aktiv.

Was kann ich mit dem SDK bauen, das in der Caramel-App nicht geht?

Funktional nichts Neues – das SDK ruft dieselben Vorgänge auf, die auch in der App verfügbar sind. Was es hinzufügt, ist Automatisierung: sie aus Ihrem eigenen Zeitplan, Ihrer Pipeline oder Ihrem internen Tool auszulösen, statt dass eine Person durch die Oberfläche klickt.

Unterstützt das SDK serverseitige und clientseitige Nutzung?

Es ist für die serverseitige Nutzung gebaut – die Credential- und Ingest-Key-Flows setzen eine vertrauenswürdige Umgebung voraus. Es wird als ESM- und CommonJS-Build mit enthaltenen TypeScript-Typen ausgeliefert.

Starten Sie mit einem Caramel-Workspace

Der SDK-Zugang wird pro Workspace vergeben. Erstellen Sie Ihren Workspace und fordern Sie Zugang an — wir teilen das Paket und die aktuelle Dokumentation.

Jetzt starten