Хранилище проекта (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): Удаляет пару ключ-значение по указанному ключу.

Ограничения

• Не более 100 ключей на проект

• key - до 1000 символов

• value - до 10000 символов

• ttl - в секундах, максимум 3600 * 24 * 100 (100 дней)

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

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

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

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, только если с момента последней отправки прошел как минимум один час.

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);
        // Можно добавить логику для повторной попытки или аларма для администратора
    }
}