ultra-telegram-framework 1.0.3

package/dist/session/gas-hybrid-storage.js

@@ -0,0 +1,49 @@
+import { PropertiesStorage } from './gas-storage';
+import { CacheStorage } from './gas-cache-storage';
+/**
+ * Hybrid storage for Google Apps Script (CacheService + PropertiesService).
+ * Combines cache speed and properties reliability.
+ */
+export class GasHybridStorage {
+    /**
+     * Hybrid storage for Google Apps Script (CacheService + PropertiesService).
+     * Combines cache speed and properties reliability.
+     * @param options Configuration options
+     * @param options.cache Which cache service to use (ScriptCache by default)
+     * @param options.properties Which properties service to use (ScriptProperties by default)
+     * @param options.ttl Time to live in seconds (21600 - 6 hours by default)
+     * @param options.prefix Prefix for keys
+     */
+    constructor(options) {
+        this.cache = new CacheStorage(options === null || options === void 0 ? void 0 : options.cache, options === null || options === void 0 ? void 0 : options.ttl, options === null || options === void 0 ? void 0 : options.prefix);
+        this.properties = new PropertiesStorage(options === null || options === void 0 ? void 0 : options.properties, options === null || options === void 0 ? void 0 : options.prefix);
+    }
+    async get(key) {
+        // 1. Try to get from the fast cache
+        let data = await Promise.resolve(this.cache.get(key));
+        if (data != null) {
+            return data;
+        }
+        // 2. If not in cache, go to slow properties
+        data = await Promise.resolve(this.properties.get(key));
+        // 3. If found in properties, update cache for next time
+        if (data !== null && data !== undefined) {
+            this.cache.set(key, data);
+        }
+        return data;
+    }
+    async set(key, value) {
+        // Write to both storages
+        await Promise.all([
+            Promise.resolve(this.cache.set(key, value)),
+            Promise.resolve(this.properties.set(key, value))
+        ]);
+    }
+    async delete(key) {
+        // Delete from both places
+        await Promise.all([
+            Promise.resolve(this.cache.delete(key)),
+            Promise.resolve(this.properties.delete(key))
+        ]);
+    }
+}

package/dist/session/gas-storage.d.ts

@@ -0,0 +1,24 @@
+import { Storage } from './storage';
+/**
+ * Session storage for Google Apps Script based on PropertiesService.
+ * Allows storing state between different requests (doPost).
+ *
+ * ✅ Pros: reliable, no 6-hour limit, well-suited for large data
+ * ❌ Cons: slower than CacheService, has a limit of 500 requests/day
+ */
+export declare class PropertiesStorage<T> implements Storage<T> {
+    private service;
+    private prefix;
+    /**
+     * @param service Which service to use (ScriptProperties by default)
+     * @param prefix Prefix for keys in storage (to avoid mixing with other settings)
+     */
+    constructor(service?: GoogleAppsScript.Properties.Properties, prefix?: string);
+    get(key: string): T | undefined;
+    set(key: string, value: T): void;
+    delete(key: string): void;
+    /**
+     * Clear ALL sessions with this prefix
+     */
+    clearAll(): void;
+}

package/dist/session/gas-storage.js

@@ -0,0 +1,47 @@
+/**
+ * Session storage for Google Apps Script based on PropertiesService.
+ * Allows storing state between different requests (doPost).
+ *
+ * ✅ Pros: reliable, no 6-hour limit, well-suited for large data
+ * ❌ Cons: slower than CacheService, has a limit of 500 requests/day
+ */
+export class PropertiesStorage {
+    /**
+     * @param service Which service to use (ScriptProperties by default)
+     * @param prefix Prefix for keys in storage (to avoid mixing with other settings)
+     */
+    constructor(service = PropertiesService.getScriptProperties(), prefix = 'session:') {
+        this.service = service;
+        this.prefix = prefix;
+    }
+    get(key) {
+        const raw = this.service.getProperty(this.prefix + key);
+        if (!raw)
+            return undefined;
+        try {
+            return JSON.parse(raw);
+        }
+        catch (e) {
+            console.error(`Error parsing session for key ${key}:`, e);
+            return undefined;
+        }
+    }
+    set(key, value) {
+        const raw = JSON.stringify(value);
+        this.service.setProperty(this.prefix + key, raw);
+    }
+    delete(key) {
+        this.service.deleteProperty(this.prefix + key);
+    }
+    /**
+     * Clear ALL sessions with this prefix
+     */
+    clearAll() {
+        const all = this.service.getProperties();
+        for (const key in all) {
+            if (key.startsWith(this.prefix)) {
+                this.service.deleteProperty(key);
+            }
+        }
+    }
+}

package/dist/session/index.d.ts

@@ -0,0 +1,28 @@
+import { Context } from '../core/context';
+import { Storage } from './storage';
+export interface SessionData extends Record<string, unknown> {
+}
+declare module '../core/context' {
+    interface Context {
+        session?: SessionData;
+    }
+}
+export interface SessionOptions<S extends SessionData> {
+    /** Data storage (MemoryStorage by default) */
+    storage?: Storage<S>;
+    /** Key generation function ("chatId:userId" by default) */
+    getSessionKey?: (ctx: Context) => string | undefined;
+    /** Empty session initialization function (if data doesn't exist yet) */
+    initial: () => S;
+}
+/**
+ * Middleware for adding sessions to the context.
+ */
+export declare function SessionManager<S extends SessionData>(options: SessionOptions<S>): (ctx: Context & {
+    session: S;
+}, next: () => Promise<void>) => Promise<void>;
+export * from './storage';
+export * from './memory-storage';
+export * from './gas-storage';
+export * from './gas-cache-storage';
+export * from './gas-hybrid-storage';

package/dist/session/index.js

@@ -0,0 +1,43 @@
+import { MemoryStorage } from './memory-storage';
+/**
+ * Middleware for adding sessions to the context.
+ */
+export function SessionManager(options) {
+    const storage = options.storage || new MemoryStorage();
+    const getSessionKey = options.getSessionKey || ((ctx) => {
+        var _a;
+        const chatId = ctx.chatId;
+        const fromId = (_a = ctx.from) === null || _a === void 0 ? void 0 : _a.id;
+        if (chatId == null || fromId == null) {
+            return undefined; // If this is an event without chat/user, the session will not work
+        }
+        return `${chatId}:${fromId}`;
+    });
+    return async (ctx, next) => {
+        const key = getSessionKey(ctx);
+        // If the key is not generated (e.g., system update), just proceed further
+        if (!key) {
+            return next();
+        }
+        // 1. Get data from storage
+        let sessionData = await Promise.resolve(storage.get(key));
+        // 2. If data is missing, call initial() or create an empty object
+        if (sessionData == null) {
+            sessionData = options.initial();
+        }
+        // 3. Put the session into the context
+        ctx.session = sessionData;
+        await next();
+        if (ctx.session == null) {
+            await Promise.resolve(storage.delete(key));
+        }
+        else {
+            await Promise.resolve(storage.set(key, ctx.session));
+        }
+    };
+}
+export * from './storage';
+export * from './memory-storage';
+export * from './gas-storage';
+export * from './gas-cache-storage';
+export * from './gas-hybrid-storage';

package/dist/session/memory-storage.d.ts

@@ -0,0 +1,28 @@
+import { Storage } from './storage';
+/**
+ * In-memory session storage (Map).
+ * Fastest option, but data is lost when the bot restarts.
+ *
+ * ✅ Pros: very fast, no configuration required
+ * ❌ Cons: data is not persistent between restarts
+ */
+export declare class MemoryStorage<T> implements Storage<T> {
+    private store;
+    /**
+     * Retrieves a session.
+     * @param key Session key
+     * @returns `T | undefined`
+     */
+    get(key: string): T | undefined;
+    /**
+     * Saves a session.
+     * @param key Session key
+     * @param value Session value
+     */
+    set(key: string, value: T): void;
+    /**
+     * Deletes a session.
+     * @param key Session key
+     */
+    delete(key: string): void;
+}

package/dist/session/memory-storage.js

@@ -0,0 +1,35 @@
+/**
+ * In-memory session storage (Map).
+ * Fastest option, but data is lost when the bot restarts.
+ *
+ * ✅ Pros: very fast, no configuration required
+ * ❌ Cons: data is not persistent between restarts
+ */
+export class MemoryStorage {
+    constructor() {
+        this.store = new Map();
+    }
+    /**
+     * Retrieves a session.
+     * @param key Session key
+     * @returns `T | undefined`
+     */
+    get(key) {
+        return this.store.get(key);
+    }
+    /**
+     * Saves a session.
+     * @param key Session key
+     * @param value Session value
+     */
+    set(key, value) {
+        this.store.set(key, value);
+    }
+    /**
+     * Deletes a session.
+     * @param key Session key
+     */
+    delete(key) {
+        this.store.delete(key);
+    }
+}

package/dist/session/storage.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Interface for session storage.
+ * T - type of session data we store.
+ */
+export interface Storage<T> {
+    /**
+     * Get session data by key.
+     */
+    get(key: string): Promise<T | undefined> | T | undefined;
+    /**
+     * Save session data by key.
+     */
+    set(key: string, value: T): Promise<void> | void;
+    /**
+     * Delete session (e.g., if the user finished the dialogue).
+     */
+    delete(key: string): Promise<void> | void;
+}

package/dist/session/storage.js

@@ -0,0 +1,2 @@
+// src/session/storage.ts
+export {};