Хранилище проекта (projectStorage)

projectStorage — это инструмент для хранения временных данных на уровне всего проекта. Он идеально подходит для кеширования данных, временных токенов авторизации и другой информации, которая должна быть доступна из любого сниппета для всех пользователей вашего проекта.

Данные, сохраненные в projectStorage, являются общими для всего проекта, что позволяет разным сниппетам и разным пользователям обмениваться информацией.

Основные методы

Метод	Описание
projectStorage.set(key, value, ttl)	Сохраняет value под именем key на ttl секунд. ttl (time-to-live) — это время жизни записи в секундах.
projectStorage.get(key)	Возвращает значение по ключу key. Если ключ не найден или время жизни истекло, вернёт null.
projectStorage.keys()	Возвращает массив всех существующих (не истёкших) ключей.
projectStorage.delete(key)	Удаляет пару ключ–значение по указанному ключу.

warning

Ограничения

• Не более 100 ключей на проект
• key - до 1000 символов
• value - до 10000 символов
• ttl - в секундах, максимум 3600 * 24 * 100 (100 дней)

Примеры использования

Пример 1: Кеширование токена авторизации

В этом примере мы сохраняем токен, получаем список всех ключей, читаем данные и затем удаляем их.

token-cache.js

async function snippet (core = new Core(), context = new Context(), projectStorage = new ProjectStorage()) {
    // Сохраняем значение '12345' под ключом 'myToken' на 5 минут (300 секунд).
    await projectStorage.set('myToken', '12345', 300);

    // Получаем массив всех ключей.
    let keys = await projectStorage.keys();
    console.log('All keys:', keys); // Выведет: All keys: [ 'myToken' ]

    // Получаем данные по ключу 'myToken'.
    let data = await projectStorage.get('myToken');
    console.log('Token data:', data); // Выведет: Token data: 12345

    // Удаляем запись по ключу.
    await projectStorage.delete('myToken');
    
    // Проверяем, что ключ удален
    let deletedData = await projectStorage.get('myToken');
    console.log('Data after deletion:', deletedData); // Выведет: Data after deletion: null
}

Пример 2: Отправка уведомлений с контролем частоты

С помощью projectStorage можно гарантировать, что критически важное уведомление (например, в Telegram или внешнюю систему аналитики) будет отправлено не чаще, чем один раз в заданный промежуток времени. Это полезно, чтобы избежать спама при частом срабатывании одного и того же сценария.

В этом примере сниппет отправляет уведомление в Telegram, только если с момента последней отправки прошел как минимум один час.

telegram-notification.js

async function snippet (core = new Core(), context = new Context(), projectStorage = new ProjectStorage()) {
    // Уникальный ключ для отслеживания последнего вызова этого сценария
    const notificationKey = 'last_critical_scenario_trigger';
    
    // Промежуток времени в секундах, в течение которого уведомление не будет отправляться повторно (1 час = 3600 секунд)
    const cooldownSeconds = 3600;

    // Получаем время последнего успешного уведомления
    const lastTriggerTimestamp = await projectStorage.get(notificationKey);

    const now = Math.floor(Date.now() / 1000); // Текущее время в секундах

    // Проверяем, прошло ли достаточно времени с последнего вызова
    if (lastTriggerTimestamp && (now - lastTriggerTimestamp < cooldownSeconds)) {
        // Еще не время, выходим из сниппета
        console.log(`Уведомление уже отправлялось. Повторная отправка будет возможна через ${cooldownSeconds - (now - lastTriggerTimestamp)} сек.`);
        return;
    }

    // Если проверка пройдена, отправляем уведомление во внешнюю систему
    try {
        await axios.post('https://api.telegram.org/bot<YOUR_BOT_TOKEN>/sendMessage', {
            chat_id: '<YOUR_CHAT_ID>',
            text: `Внимание! Сработал критический сценарий в проекте ${context.project_id}!`
        });
        
        console.log('Уведомление в Telegram успешно отправлено.');
        
        // В случае успеха — обновляем время последнего вызова в хранилище
        await projectStorage.set(notificationKey, now, cooldownSeconds);

    } catch (error) {
        console.error('Ошибка при отправке уведомления:', error.message);
        // Можно добавить логику для повторной попытки или аларма для администратора
    }
}