Yemot API Client (yemot-api2)

ספריית JS/TS מודרנית ונוחה לעבודה מול ה-API של ימות המשיח.

⚠️ שימו לב: הספרייה נמצאת כרגע בפיתוח פעיל. ייתכנו שינויים ב-API ושינויים שאינם תומכים לאחור. מומלץ להשתמש בזהירות בפרויקטים בסביבת ייצור (Production).

✨ תכונות עיקריות

• ✅ חווית פיתוח מעולה (DX) בזכות TypeScript: כל פונקציה מגיעה עם תיעוד, טיפוסים (types), ומבנה ברור לבקשות ולתשובות. תגידו שלום לניחושים ושלום להשלמה אוטומטית חכמה (IntelliSense).
• ✅ תמיכה מובנית ב-ES Modules (import) ו-CommonJS (require).
• ✅ טיפול אוטומטי בטוקן האימות.
• ✅ ממשק נוח ופשוט מבוסס Promise-ים (מוכן לעבודה עם async/await).
• ✅ כיסוי למגוון פעולות נפוצות כמו קבלת מידע, העלאה והורדת קבצים וניהול שלוחות.

🚀 התקנה

npm install yemot-api2

🛠️ שימוש בסיסי

מומלץ לשמור את מפתח הגישה במשתני סביבה (למשל, בקובץ .env) ולא ישירות בקוד. הדוגמאות הבאות כתובות ב-TypeScript כדי להדגים את העוצמה המלאה של הספרייה, כולל בדיקת טיפוסים בזמן כתיבת הקוד. גם אם אתם משתמשים ב-JavaScript טהור, עדיין תיהנו מהשלמה אוטומטית בזכות קבצי הטיפוסים הכלולים בחבילה.

// main.ts
import { YemotAPI, IGetSessionResponse } from 'yemot-api2';
import 'dotenv/config'; // For loading .env file

// 1. יצירת מופע של הלקוח
const api = new YemotAPI(process.env.YEMOT_API_KEY);

// 2. קריאה למתודות ה-API
async function main() {
  try {
    // קבלת פרטי המערכת
    console.log('Fetching session info...');
    const sessionInfo: IGetSessionResponse = await api.getSession();
    console.log(`Hello ${sessionInfo.name}! You have ${sessionInfo.units} units.`);

    // קבלת מידע על שלוחה
    console.log('\nFetching IVR directory...');
    const ivrDir = await api.getIVR2Dir({ path: '/' });
    console.log(`Found ${ivrDir.dirs.length} directories in root.`);
  
  } catch (error) {
    console.error('API call failed:', error.message);
  }
}

main();

דוגמה: העלאת קובץ

import * as fs from 'fs';
import * as path from 'path';

async function uploadAudio() {
  try {
    const filePath = path.join(__dirname, 'audio.mp3');
    const fileBuffer = fs.readFileSync(filePath);

    console.log('Uploading file...');
    const response = await api.uploadFile({
      path: 'ivr2:/1/MyNewFile.wav', // נתיב יעד בשרת
      file: fileBuffer,
      fileName: 'audio.mp3', // שם הקובץ המקורי
      convertAudio: true // בקשה להמיר את קובץ האודיו
    });

    console.log('File uploaded successfully!', response);
  } catch (error) {
    console.error('Upload failed:', error.message);
  }
}

// uploadAudio();

  // main.js
  const { YemotAPI } = require('yemot-api2'); // או import אם אתם משתמשים ב-ES Modules
  require('dotenv').config();

  const api = new YemotAPI(process.env.YEMOT_API_KEY);

  async function main() {
    try {
      console.log('Fetching session info...');
      const sessionInfo = await api.getSession();
      // גם בקובץ JS, תקבלו השלמה אוטומטית למאפיינים כמו sessionInfo.email
      console.log(`Hello ${sessionInfo.name}! You have ${sessionInfo.units} units.`);
    } catch (error) {
      console.error('API call failed:', error.message);
    }
  }

  main();

📚 מתודות עיקריות (API)

הרשימה הבאה מציגה את הפונקציות המרכזיות הנתמכות כרגע:

כללי

• getSession(): קבלת פרטי המערכת הכלליים (שם, יחידות, מייל וכו').
• getIncomingCalls(): קבלת רשימת השיחות הפעילות במערכת.

ניהול תוכן (קבצים ושלוחות)

• getIVR2Dir(params): קבלת מידע מלא על שלוחה, כולל רשימת קבצים, תיקיות והגדרות.
• updateExtension(params): יצירה או עדכון של הגדרות בשלוחה (קובץ ext.ini).
• uploadFile(params): העלאת קובץ למערכת.
• downloadFile(params): הורדת קובץ מהמערכת.
• checkIfFileExists(params): בדיקה האם קובץ קיים במערכת.
• checkIfFolderExists(params): בדיקה האם תיקייה קיימת במערכת. במקרה של תיקייה חסרה, הספרייה מטפלת בבאג של ימות שבו מוחזר responseStatus="ERROR" יחד עם folderExists=false.

שליחת צינתוק

• runTzintuk(params): שליחת צינתוק למספרים, רשימות תפוצה או רשימות צינתוקים חינמיים, עם אפשרות לזיהוי יוצא מותאם או רנדומלי (לאימות). הממשק גמיש ומאפשר שילוב בין סוגי שליחה שונים, כולל הגדרת זיהוי יוצא לכל מספר או קבוצה.

קמפיינים

• runCampaign(params?): הפעלת קמפיין חיוג יוצא על בסיס תבנית קיימת במערכת. ניתן להריץ על תבנית ברירת המחדל (ללא פרמטרים) או להתאים אישית תבנית (templateId), זיהוי יוצא (callerId), רשימת מספרים עם מידע אישי (phones), הקראה ממוחשבת (ttsMode) וקמפיין משולב SMS (withSMS).

const res = await api.runCampaign({
  templateId: 1117319,
  phones: [
    { phone: '0773137770', name: 'שם', moreinfo: 'הודעת בדיקה' },
  ],
  ttsMode: true,
});
console.log(`Campaign ${res.campaignId} started, ${res.pending} numbers pending.`);

⚠️ טיפול בשגיאות

כאשר ה-API של ימות מחזיר תגובת שגיאה (responseStatus שאינו "OK"), הספרייה זורקת YemotAPIError. בשונה מ-Error רגיל, המחלקה חושפת את קוד השגיאה המובנה (messageCode), את הסטטוס (responseStatus) ואת תגובת השרת המלאה (response), כדי לאפשר טיפול תכנותי בשגיאות ספציפיות.

YemotAPIError יורשת מ-Error, כך שקוד קיים שמסתמך על error.message ממשיך לעבוד ללא שינוי.

עבור פקודת runCampaign קיים גם ה-enum RunCampaignErrorCode עם כל קודי השגיאה המתועדים (למשל: תבנית לא חוקית, אין מספיק יחידות, ניסיון בשבת/יום טוב).

import { YemotAPI, YemotAPIError, RunCampaignErrorCode } from 'yemot-api2';

try {
  await api.runCampaign({ templateId: 1117319 });
} catch (error) {
  if (error instanceof YemotAPIError) {
    switch (error.messageCode) {
      case RunCampaignErrorCode.IsKodesh:
        console.error('לא ניתן להפעיל קמפיין בשבת/יום טוב');
        break;
      case RunCampaignErrorCode.InsufficientUnits:
        console.error('אין מספיק יחידות במערכת');
        break;
      default:
        console.error(`שגיאת קמפיין [${error.messageCode}]: ${error.message}`);
    }
  } else {
    throw error;
  }
}

🤝 תרומה לפרויקט

הפרויקט פתוח לתרומות! אם מצאתם באג, יש לכם רעיון לפיצ'ר חדש או שתרצו לשפר את התיעוד, אתם מוזמנים לפתוח Issue או Pull Request במאגר ה-GitHub.

📄 רישיון

הפרויקט מופץ תחת רישיון ISC.