Caramel SDK
حزمة تطوير برمجية TypeScript لإنشاء وتنقيح ونشر حملات كراميل والقوالب من كودك الخاص — العمليات نفسها التي ينفذها فريقك يدوياً داخل تطبيق كراميل، أصبحت قابلة للاستدعاء من سكربت. بلا اعتماديات وقت التشغيل، مبنية على fetch الأصلي.
ما قبل الإصدار 1.0 — لم تُنشر بعد على سجل npm العام
يذكر ملف README الخاص بـ @caramel/sdk ذلك بوضوح: سطح الـ API ونموذج المصادقة ما زالا قيد التغيير. اطلب الوصول وسنشارك الحزمة والوثائق الحالية مباشرةً مع مساحة عملك.
بمجرد حصول مساحة عملك على الوصول:
Node.js 18 أو أحدث. عنوان القاعدة الافتراضي هو api.caramelme.com.
npm install @caramel/sdk - ثلاث طرق للمصادقة:
-
CaramelSDK.fromCredentials({ email, password }) — تسجيل الدخول مباشرة -
new CaramelSDK({ accessToken, refreshToken? }) — إعادة استخدام رمز جلسة قائم -
CaramelSDK.fromIngestKey('ck_live_…') — يقتصر على وحدة customers فقط
سجّل الدخول، ابحث عن نشاط تجاري، وأنشئ مسودة حملة:
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); ما يمكنك استدعاؤه
أربع وحدات، تطابق ما هو مُنفَّذ ومتاح فعلياً في الحزمة اليوم.
| الوحدة | الطرق | ملاحظات |
|---|---|---|
| businesses | list() | يسرد الأنشطة التجارية التي يمكن لبيانات اعتمادك الوصول إليها. |
| campaigns | list()get()generate()refine()deploy()pause()resume()delete()suggest() | ينشئ وينقّح ويُصدر إصدارات ويجدول ويدير دورة حياة مسودة الحملة كاملةً. |
| templates | list()deploy() | يسرد مكتبة القوالب وينشر قالباً كنقطة بداية. |
| customers | identify()identifyBatch()track()purchase()trackBatch()unmap()forget() | متاحة في كود الحزمة. نقاط النهاية الخلفية ليست مُفعّلة بعد في الإنتاج — لا تبنِ عليها بعد. |
ما الذي يمكنك بناؤه
لا يضيف SDK إمكانات جديدة مقارنةً بتطبيق كراميل — بل يضيف الأتمتة. إليك كيف يبدو ذلك عملياً.
حملات مجدولة من محفزاتك الخاصة
ادمج generate_campaign وdeploy() في مهمة cron، أو خط أنابيب بيانات، أو أداة داخلية. اكتب حملة استعادة كل يوم إثنين دون فتح تطبيق كراميل.
أدوات داخلية لغير المسوّقين
ابنِ لوحة خفيفة أو أمر Slack يستدعي campaigns.suggest() وcampaigns.generate()، بحيث يستطيع أي شخص في الفريق إنشاء مسودة دون تعلّم واجهة كراميل.
نشر القوالب عبر عدة مساحات عمل
إذا كنت تدير أكثر من نشاط تجاري في كراميل — وكالات، فرانشايز — امرر عبر businesses.list() وانشر قالباً باستخدام templates.deploy() بدلاً من تكرار الإعداد اليدوي لكل حساب.
سير مراجعة خاص بك
تتضمن كل استجابة من generate_campaign validationStatus وevaluationScores. ابنِ طابور موافقة خاصاً بك أو إشعار Slack فوق ذلك، بدلاً من الاعتماد على شاشة المراجعة في تطبيق كراميل.
حالات الاستخدام
طرق واقعية تستخدم بها الفرق SDK، مبنية على ما تفعله الواجهة البرمجية فعلياً.
حملات استعادة مجدولة
يدمج فريق نمو generate_campaign في مهمة cron أسبوعية تكتب حملة استعادة للعملاء غير النشطين منذ 60 يوماً أو أكثر، ثم ينشر المسودة على Slack ليراجعها شخص وينشرها.
أدوات وكالة متعددة المساحات
تبني وكالة تدير عشرات مساحات عمل كراميل أداة داخلية تمرّ عبر businesses.list() وتنشئ مسودة حملة شهرية لكل عميل من سكربت واحد، بدلاً من الدخول إلى كل مساحة يدوياً.
مراجعة الحملات مدمجة في CI
يضيف فريق خطوة إلى عملية المراجعة الخاصة به تستدعي refine_campaign مقابل دليل أسلوب قبل الموافقة على مسودة للإرسال، فتكتشف مشكلات النبرة أو الامتثال قبل أن يراها إنسان.
توحيد القوالب على نطاق واسع
يستخدم مسؤول عمليات templates.deploy() في سكربت لنشر قالب موسمي محدّث على كل نشاط تجاري في محفظته دفعة واحدة، بدلاً من تكرار الخطوات نفسها لكل مساحة عمل.
معالجة الأخطاء
كل فشل يطلق CaramelError مع رمز .code قابل للقراءة آلياً:
AUTH_FAILEDUNAUTHORIZEDINSUFFICIENT_CREDITSTIER_UPGRADE_REQUIREDCAMPAIGN_DEPLOYEDVALIDATION_FAILEDNOT_FOUNDSERVER_ERRORNETWORK_ERRORCONFLICTCUSTOMER_SUPPRESSEDRATE_LIMITEDPAYLOAD_TOO_LARGE أسئلة قبل البدء
هل @caramel/sdk متاحة على npm؟
ليس بعد. لم تُنشر الحزمة على سجل npm العام. اطلب الوصول وسنشارك الحزمة وتعليمات التثبيت الحالية معك مباشرة.
هل الـ SDK مستقر؟
لا — ما زال في مرحلة ما قبل الإصدار 1.0. يذكر ملف README الخاص بالـ SDK أن سطح الـ API ونموذج المصادقة ما زالا قيد التغيير. توقّع تغييرات جوهرية قبل إصدار 1.0.
هل يمكنني استخدام وحدة customers؟
ليس في الإنتاج بعد. متاحة في كود الحزمة، لكن نقاط نهايتها الخلفية تُعيد حالياً خطأ 404. كل ما يخص businesses وcampaigns وtemplates مُفعّل.
ما الذي أستطيع بناءه بالـ SDK ولا أستطيعه في تطبيق كراميل؟
لا شيء جديد من ناحية الإمكانات — يستدعي SDK العمليات نفسها المتاحة في التطبيق. ما يضيفه هو الأتمتة: تشغيلها من جدولك أو خط أنابيبك أو أداتك الداخلية بدلاً من أن ينقر شخص عبر الواجهة.
هل يدعم SDK الاستخدام من جهة الخادم والعميل؟
إنه مبني للاستخدام من جهة الخادم — تفترض تدفقات بيانات الاعتماد ومفتاح الإدخال بيئة موثوقة. يُشحن كبناء ESM وCommonJS مع أنواع TypeScript مضمّنة.
ابدأ بمساحة عمل في كراميل
يُمنح الوصول إلى SDK لكل مساحة عمل. أنشئ مساحتك، ثم اطلب الوصول وسنشارك معك الحزمة والوثائق الحالية.
ابدأ الآن