@adriangalilea/utils 0.7.0 → 0.9.0

package/dist/bot/message-history.js

@@ -0,0 +1,111 @@
+/**
+ * Per-user rolling message history for GramIO bots — opt-in, with
+ * retention.
+ *
+ * Follows the same shared-session pattern as `bot/language`: the
+ * user creates a `session()` once at bot level, and each feature
+ * plugin (including this one) declares it as a dependency. gramio
+ * dedupes the runtime extension; the types flow.
+ *
+ * ## What this plugin owns
+ *
+ *   - Appends each incoming user message to `ctx.session.history.items`
+ *   - Prunes entries older than `retentionDays` or beyond `maxMessages`
+ *   - Exposes a read-only pruned snapshot at `ctx.history` for handlers
+ *
+ * ## GDPR caveat — retention IS personal data
+ *
+ * Unlike `bot/language` (preference data, covered by Telegram's standard
+ * privacy policy), retaining user **message content** is the one thing
+ * the [standard policy](https://telegram.org/privacy-tpa) does NOT cover
+ * by default. If you extend `messageHistory`, you should:
+ *
+ *   1. Set a custom `privacy` URL on your `botMenu` describing what you
+ *      retain and for how long.
+ *   2. Pass `personalData: { storage }` to your `botMenu` so 🗑 Forget
+ *      and 📥 Export buttons appear — letting users see and delete
+ *      the data you keep about them.
+ *
+ * These are not enforced by this plugin (would couple it to menu); they
+ * are documented as the bot author's legal responsibility.
+ *
+ * ## Storage layout
+ *
+ * Lives entirely inside the shared session record:
+ *
+ *   storage[String(senderId)] = {
+ *     ...other plugins' fields,
+ *     history: { items: [HistoryEntry, ...] }
+ *   }
+ *
+ * Peer deps: `gramio`, `@gramio/session`.
+ *
+ * @example
+ * import { Bot } from 'gramio'
+ * import { session } from '@gramio/session'
+ * import { redisStorage } from '@gramio/storage-redis'
+ * import { messageHistory } from '@adriangalilea/utils/bot/message-history'
+ *
+ * const userSession = session({ storage: redisStorage(), key: 'session', initial: () => ({}) })
+ *
+ * const history = messageHistory({
+ *   session: userSession,
+ *   maxMessages: 100,
+ *   retentionDays: 7,
+ * })
+ *
+ * const bot = new Bot(process.env.BOT_TOKEN!)
+ *   .extend(userSession)
+ *   .extend(history.plugin)
+ *   .command('replay', (ctx) => {
+ *     const last = ctx.history.slice(-3).map((e) => e.text).join('\n---\n')
+ *     return ctx.send(last || '(no history)')
+ *   })
+ */
+import { Plugin } from 'gramio';
+// ─── helpers ───────────────────────────────────────────────────────
+const prune = (items, maxMessages, retentionDays) => {
+    const cutoffSec = Math.floor(Date.now() / 1000) - retentionDays * 86400;
+    const fresh = items.filter((e) => e.date >= cutoffSec);
+    return fresh.slice(-maxMessages);
+};
+// ─── feature factory ───────────────────────────────────────────────
+export const messageHistory = (opts) => {
+    if (opts.maxMessages <= 0)
+        throw new Error('messageHistory: maxMessages must be > 0');
+    if (opts.retentionDays <= 0)
+        throw new Error('messageHistory: retentionDays must be > 0');
+    const plugin = buildHistoryPlugin({
+        sessionPlugin: opts.session,
+        maxMessages: opts.maxMessages,
+        retentionDays: opts.retentionDays,
+    });
+    return { plugin };
+};
+// ─── plugin builder ────────────────────────────────────────────────
+const buildHistoryPlugin = (args) => {
+    const { sessionPlugin, maxMessages, retentionDays } = args;
+    return new Plugin('@adriangalilea/utils/bot/message-history')
+        .extend(sessionPlugin)
+        // Record incoming messages with text. Service messages, edits,
+        // and callback queries don't append — only direct user input.
+        .on('message', async (ctx, next) => {
+        if (ctx.text !== undefined) {
+            const entry = {
+                messageId: ctx.id,
+                date: ctx.payload.date,
+                text: ctx.text,
+            };
+            const cur = ctx.session.history?.items ?? [];
+            ctx.session.history = {
+                items: [...prune(cur, maxMessages, retentionDays), entry].slice(-maxMessages),
+            };
+        }
+        return next();
+    })
+        // Pruned read-only view for handlers downstream.
+        .derive(['message', 'callback_query'], (ctx) => ({
+        history: prune(ctx.session.history?.items ?? [], maxMessages, retentionDays),
+    }));
+};
+//# sourceMappingURL=message-history.js.map

package/dist/bot/message-history.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-history.js","sourceRoot":"","sources":["../../src/bot/message-history.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AACH,OAAO,EAA0B,MAAM,EAAE,MAAM,QAAQ,CAAA;AA8CvD,sEAAsE;AAEtE,MAAM,KAAK,GAAG,CACZ,KAAqB,EACrB,WAAmB,EACnB,aAAqB,EACL,EAAE;IAClB,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,GAAG,aAAa,GAAG,KAAK,CAAA;IACvE,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,SAAS,CAAC,CAAA;IACtD,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,WAAW,CAAC,CAAA;AAClC,CAAC,CAAA;AAED,sEAAsE;AAEtE,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,IAA2B,EAAyB,EAAE;IACnF,IAAI,IAAI,CAAC,WAAW,IAAI,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAA;IACrF,IAAI,IAAI,CAAC,aAAa,IAAI,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAA;IAEzF,MAAM,MAAM,GAAG,kBAAkB,CAAC;QAChC,aAAa,EAAE,IAAI,CAAC,OAAO;QAC3B,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,aAAa,EAAE,IAAI,CAAC,aAAa;KAClC,CAAC,CAAA;IAEF,OAAO,EAAE,MAAM,EAAE,CAAA;AACnB,CAAC,CAAA;AAED,sEAAsE;AAEtE,MAAM,kBAAkB,GAAG,CAAC,IAI3B,EAAE,EAAE;IACH,MAAM,EAAE,aAAa,EAAE,WAAW,EAAE,aAAa,EAAE,GAAG,IAAI,CAAA;IAE1D,OAAO,IAAI,MAAM,CACf,0CAA0C,CAC3C;SACE,MAAM,CAAC,aAAa,CAAC;QACtB,+DAA+D;QAC/D,8DAA8D;SAC7D,EAAE,CAAC,SAAS,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE;QACjC,IAAI,GAAG,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;YAC3B,MAAM,KAAK,GAAiB;gBAC1B,SAAS,EAAE,GAAG,CAAC,EAAE;gBACjB,IAAI,EAAE,GAAG,CAAC,OAAO,CAAC,IAAI;gBACtB,IAAI,EAAE,GAAG,CAAC,IAAI;aACf,CAAA;YACD,MAAM,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,OAAO,EAAE,KAAK,IAAI,EAAE,CAAA;YAC5C,GAAG,CAAC,OAAO,CAAC,OAAO,GAAG;gBACpB,KAAK,EAAE,CAAC,GAAG,KAAK,CAAC,GAAG,EAAE,WAAW,EAAE,aAAa,CAAC,EAAE,KAAK,CAAC,CAAC,KAAK,CAC7D,CAAC,WAAW,CACb;aACF,CAAA;QACH,CAAC;QACD,OAAO,IAAI,EAAE,CAAA;IACf,CAAC,CAAC;QACF,iDAAiD;SAChD,MAAM,CAAC,CAAC,SAAS,EAAE,gBAAgB,CAAC,EAAE,CAAC,GAAG,EAAkB,EAAE,CAAC,CAAC;QAC/D,OAAO,EAAE,KAAK,CACZ,GAAG,CAAC,OAAO,CAAC,OAAO,EAAE,KAAK,IAAI,EAAE,EAChC,WAAW,EACX,aAAa,CACiB;KACjC,CAAC,CAAC,CAAA;AACP,CAAC,CAAA"}

package/dist/index.d.ts

@@ -8,6 +8,7 @@ export * from './universal/log.js';
 export * from './universal/format.js';
 export * from './universal/currency/index.js';
 export * from './offensive.js';
+export * from './say/index.js';
 export * from './platform/file.js';
 export * from './platform/dir.js';
 export * from './platform/path.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACtC,YAAY,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAA;AAGvD,cAAc,oBAAoB,CAAA;AAClC,cAAc,uBAAuB,CAAA;AACrC,cAAc,+BAA+B,CAAA;AAG7C,cAAc,gBAAgB,CAAA;AAI9B,cAAc,oBAAoB,CAAA;AAClC,cAAc,mBAAmB,CAAA;AACjC,cAAc,oBAAoB,CAAA;AAClC,cAAc,uBAAuB,CAAA;AACrC,cAAc,mBAAmB,CAAA;AACjC,cAAc,mBAAmB,CAAA;AACjC,cAAc,sBAAsB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACtC,YAAY,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAA;AAGvD,cAAc,oBAAoB,CAAA;AAClC,cAAc,uBAAuB,CAAA;AACrC,cAAc,+BAA+B,CAAA;AAG7C,cAAc,gBAAgB,CAAA;AAG9B,cAAc,gBAAgB,CAAA;AAI9B,cAAc,oBAAoB,CAAA;AAClC,cAAc,mBAAmB,CAAA;AACjC,cAAc,oBAAoB,CAAA;AAClC,cAAc,uBAAuB,CAAA;AACrC,cAAc,mBAAmB,CAAA;AACjC,cAAc,mBAAmB,CAAA;AACjC,cAAc,sBAAsB,CAAA"}

package/dist/index.js

@@ -10,6 +10,8 @@ export * from './universal/format.js';
 export * from './universal/currency/index.js';
 // Offensive programming - pure throws, zero dependencies
 export * from './offensive.js';
+// Polyglot strings — TS-enforced multi-language values
+export * from './say/index.js';
 // Platform-specific utilities
 // These will throw helpful errors in browser environment when used
 export * from './platform/file.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,8CAA8C;AAC9C,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAGtC,wCAAwC;AACxC,cAAc,oBAAoB,CAAA;AAClC,cAAc,uBAAuB,CAAA;AACrC,cAAc,+BAA+B,CAAA;AAE7C,yDAAyD;AACzD,cAAc,gBAAgB,CAAA;AAE9B,8BAA8B;AAC9B,mEAAmE;AACnE,cAAc,oBAAoB,CAAA;AAClC,cAAc,mBAAmB,CAAA;AACjC,cAAc,oBAAoB,CAAA;AAClC,cAAc,uBAAuB,CAAA;AACrC,cAAc,mBAAmB,CAAA;AACjC,cAAc,mBAAmB,CAAA;AACjC,cAAc,sBAAsB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,8CAA8C;AAC9C,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAGtC,wCAAwC;AACxC,cAAc,oBAAoB,CAAA;AAClC,cAAc,uBAAuB,CAAA;AACrC,cAAc,+BAA+B,CAAA;AAE7C,yDAAyD;AACzD,cAAc,gBAAgB,CAAA;AAE9B,uDAAuD;AACvD,cAAc,gBAAgB,CAAA;AAE9B,8BAA8B;AAC9B,mEAAmE;AACnE,cAAc,oBAAoB,CAAA;AAClC,cAAc,mBAAmB,CAAA;AACjC,cAAc,oBAAoB,CAAA;AAClC,cAAc,uBAAuB,CAAA;AACrC,cAAc,mBAAmB,CAAA;AACjC,cAAc,mBAAmB,CAAA;AACjC,cAAc,sBAAsB,CAAA"}

package/dist/say/index.d.ts

@@ -0,0 +1,62 @@
+/**
+ * `say` — TypeScript-enforced polyglot strings, framework-agnostic.
+ *
+ * A "polyglot value" is a plain object literal with one string per
+ * supported language:
+ *
+ *     { en: 'Hello', es: 'Hola' }
+ *
+ * The keys are the source of truth. There is no JSON file, no key
+ * registry, no extraction tool, no namespaces. The TS compiler
+ * enforces completeness: add a language to the plugin's `supported`
+ * list and every call site without that key becomes a compile error.
+ *
+ * Two entry points:
+ *
+ *   `say(value, lang)`  — pure resolver, no context, returns string.
+ *                          Use it for 3rd-party SDKs / cron / email
+ *                          / anything outside a bot ctx.
+ *
+ *   `ctx.say(value)`     — bot-bound; uses `ctx.lang`. Provided by
+ *                          `bot/language` (see that plugin for the
+ *                          `ctx.say.send / .edit / .answer` methods).
+ *
+ * @example
+ * import { say, type Polyglot } from '@adriangalilea/utils/say'
+ *
+ * await pushover.send({
+ *   message: say({ en: 'Drop!', es: '¡Drop!' }, user.lang),
+ * })
+ *
+ * // typing your own adapter:
+ * const notify = (msg: string | Polyglot<'en' | 'es'>, lang: 'en' | 'es') =>
+ *   transport.send(typeof msg === 'string' ? msg : say(msg, lang))
+ */
+/**
+ * A value that exists in N languages. `L` is the union of supported
+ * language tags (typically inferred from the object literal's keys).
+ *
+ * Authoring: `{ en: 'Hi', es: 'Hola' }` — TS infers `L = 'en' | 'es'`.
+ *
+ * Typing your own API: `function notify(msg: Polyglot<'en' | 'es'>)`
+ * — callers must provide both keys.
+ */
+export type Polyglot<L extends string> = Readonly<Record<L, string>>;
+/**
+ * Resolve a polyglot value to a string at `lang`.
+ *
+ * If `lang` is missing from `value`, returns the first available key
+ * (lexicographic). This is a structural fallback — it should never
+ * happen when `lang` is constrained by the same `L` as `value`'s
+ * keys; it exists only for the dynamic-string escape hatch.
+ *
+ * @example
+ * say({ en: 'Hi', es: 'Hola' }, 'es')           // → 'Hola'
+ * say({ en: 'Hi', es: 'Hola' }, 'fr')           // TS error: '"fr"' not in '"en" | "es"'
+ *
+ * @example  // typing-loose escape hatch with `as Polyglot<string>`
+ * const raw: Polyglot<string> = JSON.parse(blob)
+ * say(raw, userLang)                            // dynamic, falls back if missing
+ */
+export declare const say: <L extends string>(value: Polyglot<L>, lang: L) => string;
+//# sourceMappingURL=index.d.ts.map

package/dist/say/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/say/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH;;;;;;;;GAQG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,SAAS,MAAM,IAAI,QAAQ,CAAC,MAAM,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAA;AAEpE;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,GAAG,GAAI,CAAC,SAAS,MAAM,EAAE,OAAO,QAAQ,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,KAAG,MAKnE,CAAA"}

package/dist/say/index.js

@@ -0,0 +1,59 @@
+/**
+ * `say` — TypeScript-enforced polyglot strings, framework-agnostic.
+ *
+ * A "polyglot value" is a plain object literal with one string per
+ * supported language:
+ *
+ *     { en: 'Hello', es: 'Hola' }
+ *
+ * The keys are the source of truth. There is no JSON file, no key
+ * registry, no extraction tool, no namespaces. The TS compiler
+ * enforces completeness: add a language to the plugin's `supported`
+ * list and every call site without that key becomes a compile error.
+ *
+ * Two entry points:
+ *
+ *   `say(value, lang)`  — pure resolver, no context, returns string.
+ *                          Use it for 3rd-party SDKs / cron / email
+ *                          / anything outside a bot ctx.
+ *
+ *   `ctx.say(value)`     — bot-bound; uses `ctx.lang`. Provided by
+ *                          `bot/language` (see that plugin for the
+ *                          `ctx.say.send / .edit / .answer` methods).
+ *
+ * @example
+ * import { say, type Polyglot } from '@adriangalilea/utils/say'
+ *
+ * await pushover.send({
+ *   message: say({ en: 'Drop!', es: '¡Drop!' }, user.lang),
+ * })
+ *
+ * // typing your own adapter:
+ * const notify = (msg: string | Polyglot<'en' | 'es'>, lang: 'en' | 'es') =>
+ *   transport.send(typeof msg === 'string' ? msg : say(msg, lang))
+ */
+/**
+ * Resolve a polyglot value to a string at `lang`.
+ *
+ * If `lang` is missing from `value`, returns the first available key
+ * (lexicographic). This is a structural fallback — it should never
+ * happen when `lang` is constrained by the same `L` as `value`'s
+ * keys; it exists only for the dynamic-string escape hatch.
+ *
+ * @example
+ * say({ en: 'Hi', es: 'Hola' }, 'es')           // → 'Hola'
+ * say({ en: 'Hi', es: 'Hola' }, 'fr')           // TS error: '"fr"' not in '"en" | "es"'
+ *
+ * @example  // typing-loose escape hatch with `as Polyglot<string>`
+ * const raw: Polyglot<string> = JSON.parse(blob)
+ * say(raw, userLang)                            // dynamic, falls back if missing
+ */
+export const say = (value, lang) => {
+    const direct = value[lang];
+    if (typeof direct === 'string')
+        return direct;
+    for (const k in value)
+        return value[k];
+    return '';
+};
+//# sourceMappingURL=index.js.map

package/dist/say/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/say/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAaH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,GAAG,GAAG,CAAmB,KAAkB,EAAE,IAAO,EAAU,EAAE;IAC3E,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC,CAAA;IAC1B,IAAI,OAAO,MAAM,KAAK,QAAQ;QAAE,OAAO,MAAM,CAAA;IAC7C,KAAK,MAAM,CAAC,IAAI,KAAK;QAAE,OAAO,KAAK,CAAC,CAAM,CAAC,CAAA;IAC3C,OAAO,EAAE,CAAA;AACX,CAAC,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adriangalilea/utils",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "TypeScript utilities - logger, currency, formatter, GramIO bot plugins, and more",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -28,6 +28,10 @@
       "types": "./dist/universal/currency/index.d.ts",
       "default": "./dist/universal/currency/index.js"
     },
+    "./say": {
+      "types": "./dist/say/index.d.ts",
+      "default": "./dist/say/index.js"
+    },
     "./bot": {
       "types": "./dist/bot/index.d.ts",
       "default": "./dist/bot/index.js"
@@ -40,6 +44,18 @@
       "types": "./dist/bot/coalesce.d.ts",
       "default": "./dist/bot/coalesce.js"
     },
+    "./bot/language": {
+      "types": "./dist/bot/language.d.ts",
+      "default": "./dist/bot/language.js"
+    },
+    "./bot/menu": {
+      "types": "./dist/bot/menu.d.ts",
+      "default": "./dist/bot/menu.js"
+    },
+    "./bot/message-history": {
+      "types": "./dist/bot/message-history.d.ts",
+      "default": "./dist/bot/message-history.js"
+    },
     "./bot/kit": {
       "types": "./dist/bot/kit.d.ts",
       "default": "./dist/bot/kit.js"

package/dist/currency/crypto-symbols-data.d.ts

@@ -1,10 +0,0 @@
-/**
- * Generated on 2025-08-17T10:11:21.771Z
- * 13,754 cryptocurrency symbols from CoinGecko API
- *
- * Run 'npm run update-crypto' to refresh this list
- */
-export declare const cryptoSymbolsData: readonly string[];
-export declare const lastUpdated = "2025-08-17T10:11:21.771Z";
-export declare const symbolCount = 13754;
-//# sourceMappingURL=crypto-symbols-data.d.ts.map

package/dist/currency/crypto-symbols-data.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"crypto-symbols-data.d.ts","sourceRoot":"","sources":["../../src/currency/crypto-symbols-data.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAO,MAAM,iBAAiB,EAAE,SAAS,MAAM,EA27a9C,CAAA;AAED,eAAO,MAAM,WAAW,6BAA6B,CAAA;AACrD,eAAO,MAAM,WAAW,QAAQ,CAAA"}