@seip/bluebird-js 0.1.5 → 0.1.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/core/ai.js ADDED
@@ -0,0 +1,1051 @@
1
+ import crypto from "node:crypto";
2
+ import Cache from "./cache.js";
3
+ import Validator from "./validate.js";
4
+
5
+ /**
6
+ * In-memory sliding window rate limit buckets for AI calls.
7
+ * @type {Map<string, { minute?: { count: number, resetTime: number }, day?: { count: number, resetTime: number }, general?: { count: number, resetTime: number } }>}
8
+ */
9
+ const aiRateBuckets = new Map();
10
+
11
+ setInterval(() => {
12
+ if (aiRateBuckets.size === 0) return;
13
+ const now = Date.now();
14
+ for (const [key, bucket] of aiRateBuckets) {
15
+ let active = false;
16
+ if (bucket.minute && bucket.minute.resetTime > now) active = true;
17
+ if (bucket.day && bucket.day.resetTime > now) active = true;
18
+ if (bucket.general && bucket.general.resetTime > now) active = true;
19
+ if (!active) {
20
+ aiRateBuckets.delete(key);
21
+ }
22
+ }
23
+ }, 60000).unref();
24
+
25
+ /**
26
+ * Accurately extracts the client's real IP address across reverse proxies and CDNs.
27
+ * Checks Cloudflare, Akamai, Nginx, standard X-Forwarded-For, and cleans IPv6 mappings.
28
+ * @param {import('express').Request|Object} req
29
+ * @returns {string}
30
+ */
31
+ export function getClientIp(req) {
32
+ if (!req) return "127.0.0.1";
33
+
34
+ const headers = req.headers || {};
35
+
36
+ let ip =
37
+ headers["cf-connecting-ip"] ||
38
+ headers["true-client-ip"] ||
39
+ headers["x-real-ip"] ||
40
+ headers["x-forwarded-for"] ||
41
+ headers["x-client-ip"] ||
42
+ headers["x-cluster-client-ip"] ||
43
+ req.ip ||
44
+ req.socket?.remoteAddress ||
45
+ req.connection?.remoteAddress ||
46
+ "127.0.0.1";
47
+
48
+ if (typeof ip === "string") {
49
+ if (ip.includes(",")) {
50
+ ip = ip.split(",")[0].trim();
51
+ }
52
+
53
+ if (ip.startsWith("::ffff:")) {
54
+ ip = ip.slice(7);
55
+ }
56
+
57
+ if (ip === "::1") {
58
+ ip = "127.0.0.1";
59
+ }
60
+
61
+ if (ip.includes(":") && ip.includes(".") && ip.startsWith("[")) {
62
+ const match = ip.match(/^\[(.*)\](?::\d+)?$/);
63
+ if (match) ip = match[1];
64
+ } else if (/^\d+\.\d+\.\d+\.\d+:\d+$/.test(ip)) {
65
+ ip = ip.split(":")[0];
66
+ }
67
+ }
68
+
69
+ return ip || "127.0.0.1";
70
+ }
71
+
72
+ /**
73
+ * Reversibly masks sensitive keys in context data and prompt text.
74
+ * Replaces personal values with anonymous tokens like [name_01], [email_01], etc.
75
+ * @param {string} prompt
76
+ * @param {Object} [data=null]
77
+ * @param {string[]} [sensitiveKeys=[]]
78
+ * @returns {{ maskedPrompt: string, maskedData: Object|null, tokenMap: Object, reverseTokenMap: Object }}
79
+ */
80
+ export function maskSensitiveData(prompt = "", data = null, sensitiveKeys = []) {
81
+ const tokenMap = {};
82
+ const reverseTokenMap = {};
83
+ const keyCounters = {};
84
+
85
+ let maskedData = null;
86
+ if (data && typeof data === "object") {
87
+ maskedData = Array.isArray(data) ? [...data] : { ...data };
88
+ }
89
+
90
+ let maskedPrompt = typeof prompt === "string" ? prompt : String(prompt || "");
91
+
92
+ if (data && typeof data === "object" && Array.isArray(sensitiveKeys) && sensitiveKeys.length > 0) {
93
+ for (const key of sensitiveKeys) {
94
+ if (key in data && data[key] !== null && data[key] !== undefined) {
95
+ const rawVal = String(data[key]);
96
+ if (!rawVal.trim()) continue;
97
+
98
+ keyCounters[key] = (keyCounters[key] || 0) + 1;
99
+ const padIndex = String(keyCounters[key]).padStart(2, "0");
100
+ const token = `[${key}_${padIndex}]`;
101
+
102
+ tokenMap[rawVal] = token;
103
+ reverseTokenMap[token] = rawVal;
104
+ maskedData[key] = token;
105
+
106
+ const escapedVal = rawVal.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
107
+ maskedPrompt = maskedPrompt.replace(new RegExp(escapedVal, "g"), token);
108
+ }
109
+ }
110
+ }
111
+
112
+ if (maskedData && Object.keys(maskedData).length > 0) {
113
+ const serializedData = JSON.stringify(maskedData, null, 2);
114
+ if (!maskedPrompt.includes(serializedData)) {
115
+ maskedPrompt = `${maskedPrompt}\n\nContext Data:\n${serializedData}`;
116
+ }
117
+ }
118
+
119
+ return {
120
+ maskedPrompt,
121
+ maskedData,
122
+ tokenMap,
123
+ reverseTokenMap,
124
+ };
125
+ }
126
+
127
+ /**
128
+ * Reverses sensitive data masking by restoring original values into tokens.
129
+ * @param {string} text
130
+ * @param {Object} reverseTokenMap
131
+ * @returns {string}
132
+ */
133
+ export function unmaskSensitiveData(text = "", reverseTokenMap = {}) {
134
+ if (!text || typeof text !== "string") return text;
135
+ if (!reverseTokenMap || Object.keys(reverseTokenMap).length === 0) return text;
136
+
137
+ let restored = text;
138
+ for (const [token, originalVal] of Object.entries(reverseTokenMap)) {
139
+ const innerName = token.replace(/^\[|\]$/g, "").trim();
140
+ const pattern = new RegExp(`\\[\\s*${innerName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\s*\\]`, "g");
141
+ restored = restored.replace(pattern, originalVal);
142
+ }
143
+
144
+ return restored;
145
+ }
146
+
147
+ /**
148
+ * Strips markdown code blocks (e.g. ```json ... ```) from model response text.
149
+ * @param {string} text
150
+ * @returns {string}
151
+ */
152
+ export function extractJsonString(text = "") {
153
+ if (!text || typeof text !== "string") return "{}";
154
+ const trimmed = text.trim();
155
+ const match = trimmed.match(/```(?:json)?\s*([\s\S]*?)\s*```/);
156
+ if (match) {
157
+ return match[1].trim();
158
+ }
159
+ return trimmed;
160
+ }
161
+
162
+ /**
163
+ * Unified AI client supporting DeepSeek (default), Google Gemini, and OpenAI
164
+ * with automatic PII masking, 0ms prompt caching, and sliding window rate limits.
165
+ */
166
+ export class AI {
167
+ /**
168
+ * Initializes the AI client.
169
+ * @param {Object} [options={}]
170
+ * @param {"deepseek"|"gemini"|"openai"|"custom"} [options.provider="deepseek"] - Active AI provider.
171
+ * @param {string} [options.model] - Specific model name.
172
+ * @param {string} [options.apiKey] - Provider API key.
173
+ * @param {string} [options.baseURL] - Custom base endpoint URL.
174
+ * @param {number} [options.temperature=0.7] - Default sampling temperature.
175
+ * @param {boolean|Object} [options.thinking=false] - Reasoning / thinking configuration for DeepSeek.
176
+ * @param {"low"|"medium"|"high"} [options.reasoningEffort] - Reasoning effort level.
177
+ * @param {number|Object} [options.rateLimit] - Rate limiting config ({ minute, day } or { max, windowMs }).
178
+ * @param {number} [options.rateWindow=60] - Sliding window duration in seconds if rateLimit is numeric.
179
+ * @param {number|boolean} [options.cacheTtl=3600] - Prompt cache TTL in seconds (default: 3600, false to disable).
180
+ * @param {string} [options.system] - Default system instruction prompt.
181
+ */
182
+ constructor(options = {}) {
183
+ this.provider = (options.provider || "deepseek").toLowerCase().trim();
184
+ this.model = options.model || this._getDefaultModel(this.provider);
185
+ this.apiKey = options.apiKey || this._getDefaultApiKey(this.provider);
186
+ this.baseURL = options.baseURL || this._getDefaultBaseUrl(this.provider);
187
+ this.temperature = options.temperature ?? 0.7;
188
+ this.thinking = options.thinking ?? false;
189
+ this.reasoningEffort = options.reasoningEffort;
190
+ this.rateLimit = options.rateLimit;
191
+ this.rateWindow = options.rateWindow ?? 60;
192
+ this.cacheTtl = options.cacheTtl ?? 3600;
193
+ this.system = options.system || "";
194
+ }
195
+
196
+ /**
197
+ * Returns default model identifier for the selected provider.
198
+ * @private
199
+ * @param {string} provider
200
+ * @returns {string}
201
+ */
202
+ _getDefaultModel(provider) {
203
+ if (provider === "gemini") {
204
+ return "gemini-3.5-flash";
205
+ }
206
+ if (provider === "openai") {
207
+ return "gpt-4o-mini";
208
+ }
209
+ return "deepseek-flash";
210
+ }
211
+
212
+ /**
213
+ * Resolves default API key from environment variables.
214
+ * @private
215
+ * @param {string} provider
216
+ * @returns {string}
217
+ */
218
+ _getDefaultApiKey(provider) {
219
+ if (provider === "gemini") {
220
+ return process.env.GEMINI_API_KEY || "";
221
+ }
222
+ if (provider === "openai") {
223
+ return process.env.OPENAI_API_KEY || "";
224
+ }
225
+ return process.env.DEEPSEEK_API_KEY || "";
226
+ }
227
+
228
+ /**
229
+ * Resolves default base URL for the selected provider.
230
+ * @private
231
+ * @param {string} provider
232
+ * @returns {string}
233
+ */
234
+ _getDefaultBaseUrl(provider) {
235
+ if (provider === "gemini") {
236
+ return process.env.GEMINI_BASE_URL || "https://generativelanguage.googleapis.com/v1beta/interactions";
237
+ }
238
+ if (provider === "openai") {
239
+ return process.env.OPENAI_BASE_URL || "https://api.openai.com/v1/models";
240
+ }
241
+ return process.env.DEEPSEEK_BASE_URL || "https://api.deepseek.com";
242
+ }
243
+
244
+ /**
245
+ * Checks sliding window rate limit for a client identifier.
246
+ * @param {string} clientKey - Client identifier (e.g. IP address or user ID).
247
+ * @param {Object} [limitConfig=null] - Rate limit options.
248
+ * @returns {{ allowed: boolean, retryAfter: number }}
249
+ */
250
+ checkRateLimit(clientKey, limitConfig = null) {
251
+ const config = limitConfig || this.rateLimit;
252
+ if (!config || !clientKey) {
253
+ return { allowed: true, retryAfter: 0 };
254
+ }
255
+
256
+ const now = Date.now();
257
+ let bucket = aiRateBuckets.get(clientKey);
258
+ if (!bucket) {
259
+ bucket = {};
260
+ aiRateBuckets.set(clientKey, bucket);
261
+ }
262
+
263
+ if (typeof config === "number") {
264
+ const windowMs = (this.rateWindow || 60) * 1000;
265
+ if (!bucket.general || bucket.general.resetTime <= now) {
266
+ bucket.general = { count: 1, resetTime: now + windowMs };
267
+ return { allowed: true, retryAfter: 0 };
268
+ }
269
+ bucket.general.count += 1;
270
+ if (bucket.general.count > config) {
271
+ const retryAfter = Math.ceil((bucket.general.resetTime - now) / 1000);
272
+ return { allowed: false, retryAfter: Math.max(1, retryAfter) };
273
+ }
274
+ return { allowed: true, retryAfter: 0 };
275
+ }
276
+
277
+ if (config.minute !== undefined || config.day !== undefined) {
278
+ if (config.minute !== undefined) {
279
+ const minuteWindowMs = 60000;
280
+ if (!bucket.minute || bucket.minute.resetTime <= now) {
281
+ bucket.minute = { count: 1, resetTime: now + minuteWindowMs };
282
+ } else {
283
+ bucket.minute.count += 1;
284
+ if (bucket.minute.count > config.minute) {
285
+ const retryAfter = Math.ceil((bucket.minute.resetTime - now) / 1000);
286
+ return { allowed: false, retryAfter: Math.max(1, retryAfter) };
287
+ }
288
+ }
289
+ }
290
+
291
+ if (config.day !== undefined) {
292
+ const dayWindowMs = 86400000;
293
+ if (!bucket.day || bucket.day.resetTime <= now) {
294
+ bucket.day = { count: 1, resetTime: now + dayWindowMs };
295
+ } else {
296
+ bucket.day.count += 1;
297
+ if (bucket.day.count > config.day) {
298
+ const retryAfter = Math.ceil((bucket.day.resetTime - now) / 1000);
299
+ return { allowed: false, retryAfter: Math.max(1, retryAfter) };
300
+ }
301
+ }
302
+ }
303
+
304
+ return { allowed: true, retryAfter: 0 };
305
+ }
306
+
307
+ if (config.max !== undefined) {
308
+ const windowMs = config.windowMs || 60000;
309
+ if (!bucket.general || bucket.general.resetTime <= now) {
310
+ bucket.general = { count: 1, resetTime: now + windowMs };
311
+ return { allowed: true, retryAfter: 0 };
312
+ }
313
+ bucket.general.count += 1;
314
+ if (bucket.general.count > config.max) {
315
+ const retryAfter = Math.ceil((bucket.general.resetTime - now) / 1000);
316
+ return { allowed: false, retryAfter: Math.max(1, retryAfter) };
317
+ }
318
+ return { allowed: true, retryAfter: 0 };
319
+ }
320
+
321
+ return { allowed: true, retryAfter: 0 };
322
+ }
323
+
324
+ /**
325
+ * Executes an AI prompt with optional PII masking, caching, and rate limiting.
326
+ * @param {string|Array} prompt - User prompt string or messages array.
327
+ * @param {Object} [options={}] - Invocation options.
328
+ * @param {Object} [options.data] - Context data object containing sensitive information.
329
+ * @param {string[]} [options.sensitiveKeys] - Keys in data to mask before transmission.
330
+ * @param {import('express').Request|Object} [options.request] - Express request for client IP rate limiting.
331
+ * @param {import('express').Request|Object} [options.req] - Alias for request.
332
+ * @param {string} [options.user] - Custom user identifier for rate limiting.
333
+ * @param {string} [options.system] - System instruction prompt.
334
+ * @param {boolean} [options.json=false] - Whether to enforce structured JSON output.
335
+ * @param {Object} [options.schema] - Validator schema to validate structured JSON output.
336
+ * @param {number} [options.temperature] - Override temperature.
337
+ * @param {string} [options.model] - Override model name.
338
+ * @param {string} [options.provider] - Override provider.
339
+ * @param {string} [options.apiKey] - Override API key.
340
+ * @param {string} [options.baseURL] - Override base URL.
341
+ * @param {number|boolean} [options.cache] - Cache TTL in seconds (false to bypass).
342
+ * @param {boolean|Object} [options.thinking] - DeepSeek reasoning mode.
343
+ * @param {number} [options.maxTokens] - Maximum tokens to generate.
344
+ * @returns {Promise<Object>} Execution result.
345
+ */
346
+ async ask(prompt, options = {}) {
347
+ const startTime = Date.now();
348
+
349
+ const req = options.request || options.req;
350
+ const clientKey = options.user || (req ? getClientIp(req) : null);
351
+ if (clientKey) {
352
+ const rateCheck = this.checkRateLimit(clientKey, options.rateLimit);
353
+ if (!rateCheck.allowed) {
354
+ return {
355
+ success: false,
356
+ error: "rate_limit_exceeded",
357
+ message: "Rate limit exceeded. Please try again later.",
358
+ retryAfter: rateCheck.retryAfter,
359
+ };
360
+ }
361
+ }
362
+
363
+ const provider = (options.provider || this.provider).toLowerCase().trim();
364
+ const model = options.model || (options.provider ? this._getDefaultModel(provider) : this.model);
365
+ const apiKey = options.apiKey || (options.provider ? this._getDefaultApiKey(provider) : this.apiKey);
366
+ const baseURL = options.baseURL || (options.provider ? this._getDefaultBaseUrl(provider) : this.baseURL);
367
+ const temperature = options.temperature ?? this.temperature;
368
+ const systemPrompt = options.system !== undefined ? options.system : this.system;
369
+ const isJson = Boolean(options.json || options.schema);
370
+
371
+ const sensitiveKeys = options.sensitiveKeys || [];
372
+ const contextData = options.data || null;
373
+
374
+ let rawPrompt = typeof prompt === "string" ? prompt : "";
375
+ let messages = Array.isArray(prompt) ? prompt : null;
376
+
377
+ const { maskedPrompt, reverseTokenMap } = maskSensitiveData(
378
+ rawPrompt,
379
+ contextData,
380
+ sensitiveKeys
381
+ );
382
+
383
+ const effectiveCacheTtl = options.cache !== undefined ? options.cache : this.cacheTtl;
384
+ let cacheKey = null;
385
+
386
+ if (effectiveCacheTtl !== false && effectiveCacheTtl > 0) {
387
+ const hashContent = `${provider}:${model}:${systemPrompt}:${maskedPrompt}:${temperature}:${isJson ? "json" : "text"}`;
388
+ cacheKey = `ai_cache:${crypto.createHash("sha256").update(hashContent).digest("hex")}`;
389
+
390
+ try {
391
+ const cachedPayload = await Cache.get(cacheKey, { driver: "memory" });
392
+ if (cachedPayload && cachedPayload.text) {
393
+ const restoredText = unmaskSensitiveData(cachedPayload.text, reverseTokenMap);
394
+ let parsedData = null;
395
+ let isValid = true;
396
+ let validationErrors = null;
397
+
398
+ if (isJson) {
399
+ try {
400
+ parsedData = JSON.parse(extractJsonString(restoredText));
401
+ if (options.schema) {
402
+ const validator = new Validator(options.schema, "en");
403
+ const validation = await validator.validate(parsedData);
404
+ isValid = validation.success;
405
+ validationErrors = validation.errors;
406
+ }
407
+ } catch (err) {
408
+ parsedData = null;
409
+ }
410
+ }
411
+
412
+ return {
413
+ success: true,
414
+ text: restoredText,
415
+ rawText: cachedPayload.text,
416
+ parsed: parsedData,
417
+ valid: isValid,
418
+ errors: validationErrors,
419
+ cached: true,
420
+ latency: 0,
421
+ provider,
422
+ model,
423
+ usage: cachedPayload.usage || { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 },
424
+ maskedKeys: Object.keys(reverseTokenMap).length > 0 ? sensitiveKeys : [],
425
+ };
426
+ }
427
+ } catch { }
428
+ }
429
+
430
+ let responsePayload = null;
431
+ if (provider === "gemini") {
432
+ responsePayload = await this._callGemini({
433
+ prompt: maskedPrompt,
434
+ messages,
435
+ system: systemPrompt,
436
+ model,
437
+ apiKey,
438
+ baseURL,
439
+ temperature,
440
+ json: isJson,
441
+ maxTokens: options.maxTokens,
442
+ });
443
+ } else if (provider === "openai") {
444
+ responsePayload = await this._callOpenAI({
445
+ prompt: maskedPrompt,
446
+ messages,
447
+ system: systemPrompt,
448
+ model,
449
+ apiKey,
450
+ baseURL,
451
+ temperature,
452
+ json: isJson,
453
+ maxTokens: options.maxTokens,
454
+ });
455
+ } else {
456
+ responsePayload = await this._callDeepSeek({
457
+ prompt: maskedPrompt,
458
+ messages,
459
+ system: systemPrompt,
460
+ model,
461
+ apiKey,
462
+ baseURL,
463
+ temperature,
464
+ thinking: options.thinking ?? this.thinking,
465
+ reasoningEffort: options.reasoningEffort ?? this.reasoningEffort,
466
+ json: isJson,
467
+ maxTokens: options.maxTokens,
468
+ });
469
+ }
470
+
471
+ if (!responsePayload.success) {
472
+ return {
473
+ success: false,
474
+ error: responsePayload.error || "ai_call_failed",
475
+ message: responsePayload.message || "Failed to communicate with AI provider.",
476
+ provider,
477
+ model,
478
+ latency: Date.now() - startTime,
479
+ };
480
+ }
481
+
482
+ const rawModelText = responsePayload.text || "";
483
+
484
+ if (cacheKey && effectiveCacheTtl > 0) {
485
+ try {
486
+ await Cache.set(
487
+ cacheKey,
488
+ {
489
+ text: rawModelText,
490
+ provider,
491
+ model,
492
+ usage: responsePayload.usage,
493
+ },
494
+ effectiveCacheTtl,
495
+ { driver: "memory" }
496
+ );
497
+ } catch { }
498
+ }
499
+
500
+ const finalRestoredText = unmaskSensitiveData(rawModelText, reverseTokenMap);
501
+ let parsedData = null;
502
+ let isValid = true;
503
+ let validationErrors = null;
504
+
505
+ if (isJson) {
506
+ try {
507
+ parsedData = JSON.parse(extractJsonString(finalRestoredText));
508
+ if (options.schema) {
509
+ const validator = new Validator(options.schema, "en");
510
+ const validation = await validator.validate(parsedData);
511
+ isValid = validation.success;
512
+ validationErrors = validation.errors;
513
+ }
514
+ } catch (err) {
515
+ parsedData = null;
516
+ isValid = false;
517
+ validationErrors = [{ message: "Response could not be parsed as valid JSON." }];
518
+ }
519
+ }
520
+
521
+ return {
522
+ success: true,
523
+ text: finalRestoredText,
524
+ rawText: rawModelText,
525
+ parsed: parsedData,
526
+ valid: isValid,
527
+ errors: validationErrors,
528
+ reasoning: responsePayload.reasoning || null,
529
+ cached: false,
530
+ latency: Date.now() - startTime,
531
+ provider,
532
+ model,
533
+ usage: responsePayload.usage || {},
534
+ maskedKeys: Object.keys(reverseTokenMap).length > 0 ? sensitiveKeys : [],
535
+ };
536
+ }
537
+
538
+ /**
539
+ * Streams responses as an async generator yielding text chunks.
540
+ * @param {string} prompt
541
+ * @param {Object} [options={}]
542
+ * @returns {AsyncGenerator<{ text: string, done: boolean }, void, unknown>}
543
+ */
544
+ async *askStream(prompt, options = {}) {
545
+ const provider = (options.provider || this.provider).toLowerCase().trim();
546
+ const model = options.model || (options.provider ? this._getDefaultModel(provider) : this.model);
547
+ const apiKey = options.apiKey || (options.provider ? this._getDefaultApiKey(provider) : this.apiKey);
548
+ const baseURL = options.baseURL || (options.provider ? this._getDefaultBaseUrl(provider) : this.baseURL);
549
+ const temperature = options.temperature ?? this.temperature;
550
+ const systemPrompt = options.system !== undefined ? options.system : this.system;
551
+
552
+ const req = options.request || options.req;
553
+ const clientKey = options.user || (req ? getClientIp(req) : null);
554
+ if (clientKey) {
555
+ const rateCheck = this.checkRateLimit(clientKey, options.rateLimit);
556
+ if (!rateCheck.allowed) {
557
+ throw new Error("Rate limit exceeded. Please try again later.");
558
+ }
559
+ }
560
+
561
+ const sensitiveKeys = options.sensitiveKeys || [];
562
+ const contextData = options.data || null;
563
+
564
+ let rawPrompt = typeof prompt === "string" ? prompt : "";
565
+ let messages = Array.isArray(prompt) ? prompt : null;
566
+
567
+ const { maskedPrompt } = maskSensitiveData(
568
+ rawPrompt,
569
+ contextData,
570
+ sensitiveKeys
571
+ );
572
+ const targetPrompt = maskedPrompt || prompt;
573
+
574
+ if (provider === "gemini") {
575
+ const url = `${baseURL.replace(/\/+$/, "")}/v1beta/models/${model}:streamGenerateContent?alt=sse&key=${apiKey}`;
576
+ const payload = {
577
+ contents: Array.isArray(messages) && messages.length > 0
578
+ ? messages.map((m) => ({ role: m.role === "assistant" || m.role === "model" ? "model" : "user", parts: [{ text: m.content }] }))
579
+ : [{ role: "user", parts: [{ text: String(targetPrompt || "") }] }],
580
+ generationConfig: { temperature },
581
+ };
582
+ if (systemPrompt) {
583
+ payload.systemInstruction = { parts: [{ text: systemPrompt }] };
584
+ }
585
+
586
+ const res = await fetch(url, {
587
+ method: "POST",
588
+ headers: { "Content-Type": "application/json" },
589
+ body: JSON.stringify(payload),
590
+ });
591
+
592
+ if (!res.ok) {
593
+ const errorText = await res.text();
594
+ throw new Error(`Gemini Stream Error (${res.status}): ${errorText}`);
595
+ }
596
+
597
+ const reader = res.body.getReader();
598
+ const decoder = new TextDecoder();
599
+ let buffer = "";
600
+
601
+ while (true) {
602
+ const { value, done } = await reader.read();
603
+ if (done) break;
604
+ buffer += decoder.decode(value, { stream: true });
605
+ const lines = buffer.split("\n");
606
+ buffer = lines.pop() || "";
607
+
608
+ for (const line of lines) {
609
+ const trimmed = line.trim();
610
+ if (trimmed.startsWith("data:")) {
611
+ const rawData = trimmed.slice(5).trim();
612
+ if (rawData) {
613
+ try {
614
+ const parsed = JSON.parse(rawData);
615
+ const chunkText = parsed.candidates?.[0]?.content?.parts?.[0]?.text;
616
+ if (chunkText) {
617
+ yield { text: chunkText, done: false };
618
+ }
619
+ } catch { }
620
+ }
621
+ }
622
+ }
623
+ }
624
+
625
+ yield { text: "", done: true };
626
+ return;
627
+ }
628
+
629
+ const isDeepSeek = provider === "deepseek";
630
+ const endpoint = `${baseURL.replace(/\/+$/, "")}/chat/completions`;
631
+ messages = [];
632
+ if (systemPrompt) {
633
+ messages.push({ role: "system", content: systemPrompt });
634
+ }
635
+ if (Array.isArray(prompt) && prompt.length > 0) {
636
+ messages.push(...prompt);
637
+ } else {
638
+ messages.push({ role: "user", content: String(targetPrompt || "") });
639
+ }
640
+
641
+ const bodyPayload = {
642
+ model,
643
+ messages,
644
+ temperature,
645
+ stream: true,
646
+ };
647
+ if (isDeepSeek && (options.thinking ?? this.thinking)) {
648
+ bodyPayload.thinking = { type: "enabled" };
649
+ }
650
+
651
+ const res = await fetch(endpoint, {
652
+ method: "POST",
653
+ headers: {
654
+ "Content-Type": "application/json",
655
+ Authorization: `Bearer ${apiKey}`,
656
+ },
657
+ body: JSON.stringify(bodyPayload),
658
+ });
659
+
660
+ if (!res.ok) {
661
+ const errorText = await res.text();
662
+ throw new Error(`AI Stream Error (${res.status}): ${errorText}`);
663
+ }
664
+
665
+ const reader = res.body.getReader();
666
+ const decoder = new TextDecoder();
667
+ let buffer = "";
668
+
669
+ while (true) {
670
+ const { value, done } = await reader.read();
671
+ if (done) break;
672
+ buffer += decoder.decode(value, { stream: true });
673
+ const lines = buffer.split("\n");
674
+ buffer = lines.pop() || "";
675
+
676
+ for (const line of lines) {
677
+ const trimmed = line.trim();
678
+ if (trimmed.startsWith("data:")) {
679
+ const rawData = trimmed.slice(5).trim();
680
+ if (rawData === "[DONE]") {
681
+ yield { text: "", done: true };
682
+ return;
683
+ }
684
+ if (rawData) {
685
+ try {
686
+ const parsed = JSON.parse(rawData);
687
+ const delta = parsed.choices?.[0]?.delta?.content;
688
+ if (delta) {
689
+ yield { text: delta, done: false };
690
+ }
691
+ } catch { }
692
+ }
693
+ }
694
+ }
695
+ }
696
+
697
+ yield { text: "", done: true };
698
+ }
699
+
700
+ /**
701
+ * Directly pipes streamed AI output to an Express HTTP response.
702
+ * Supports Server-Sent Events (SSE) and raw chunked transfer encoding with Nginx anti-buffering.
703
+ * @param {import('express').Response} res - Express response object.
704
+ * @param {string|Array} prompt - Prompt text or messages array.
705
+ * @param {Object} [options={}] - Invocation options.
706
+ * @param {boolean} [options.sse=false] - Whether to format as Server-Sent Events (text/event-stream).
707
+ * @returns {Promise<void>}
708
+ */
709
+ async pipe(res, prompt, options = {}) {
710
+ const isSse = Boolean(options.sse);
711
+
712
+ if (isSse) {
713
+ res.setHeader("Content-Type", "text/event-stream; charset=utf-8");
714
+ res.setHeader("Cache-Control", "no-cache, no-transform");
715
+ res.setHeader("Connection", "keep-alive");
716
+ res.setHeader("X-Accel-Buffering", "no");
717
+ } else {
718
+ res.setHeader("Content-Type", "text/plain; charset=utf-8");
719
+ res.setHeader("Transfer-Encoding", "chunked");
720
+ res.setHeader("X-Accel-Buffering", "no");
721
+ }
722
+
723
+ if (typeof res.flushHeaders === "function") {
724
+ res.flushHeaders();
725
+ }
726
+
727
+ try {
728
+ for await (const chunk of this.askStream(prompt, options)) {
729
+ if (chunk.done) break;
730
+ if (chunk.text) {
731
+ if (isSse) {
732
+ res.write(`data: ${JSON.stringify({ text: chunk.text })}\n\n`);
733
+ } else {
734
+ res.write(chunk.text);
735
+ }
736
+ if (typeof res.flush === "function") {
737
+ res.flush();
738
+ }
739
+ }
740
+ }
741
+
742
+ if (isSse) {
743
+ res.write("data: [DONE]\n\n");
744
+ }
745
+ } catch (err) {
746
+ if (isSse) {
747
+ res.write(`data: ${JSON.stringify({ error: err.message })}\n\n`);
748
+ } else {
749
+ res.write(`\n[ERROR: ${err.message}]`);
750
+ }
751
+ } finally {
752
+ res.end();
753
+ }
754
+ }
755
+
756
+ /**
757
+ * Alias for pipe().
758
+ * @param {import('express').Response} res
759
+ * @param {string|Array} prompt
760
+ * @param {Object} [options={}]
761
+ * @returns {Promise<void>}
762
+ */
763
+ async stream(res, prompt, options = {}) {
764
+ return this.pipe(res, prompt, options);
765
+ }
766
+
767
+ /**
768
+ * Internal executor for DeepSeek chat completions API.
769
+ * @private
770
+ */
771
+ async _callDeepSeek({ prompt, messages, system, model, apiKey, baseURL, temperature, thinking, reasoningEffort, json, maxTokens }) {
772
+ if (!apiKey) {
773
+ return { success: false, error: "missing_api_key", message: "DEEPSEEK_API_KEY environment variable is not configured." };
774
+ }
775
+
776
+ const endpoint = `${baseURL.replace(/\/+$/, "")}/chat/completions`;
777
+ const formattedMessages = [];
778
+ if (system) {
779
+ formattedMessages.push({ role: "system", content: system });
780
+ }
781
+ if (Array.isArray(messages) && messages.length > 0) {
782
+ formattedMessages.push(...messages);
783
+ } else {
784
+ formattedMessages.push({ role: "user", content: prompt });
785
+ }
786
+
787
+ const body = {
788
+ model,
789
+ messages: formattedMessages,
790
+ temperature,
791
+ stream: false,
792
+ };
793
+
794
+ if (json) {
795
+ body.response_format = { type: "json_object" };
796
+ }
797
+ if (thinking) {
798
+ body.thinking = typeof thinking === "object" ? thinking : { type: "enabled" };
799
+ }
800
+ if (reasoningEffort) {
801
+ body.reasoning_effort = reasoningEffort;
802
+ }
803
+ if (maxTokens) {
804
+ body.max_tokens = maxTokens;
805
+ }
806
+
807
+ try {
808
+ const response = await fetch(endpoint, {
809
+ method: "POST",
810
+ headers: {
811
+ "Content-Type": "application/json",
812
+ Authorization: `Bearer ${apiKey}`,
813
+ },
814
+ body: JSON.stringify(body),
815
+ });
816
+
817
+ if (!response.ok) {
818
+ const errorBody = await response.text();
819
+ return { success: false, error: "provider_error", message: `DeepSeek Error (${response.status}): ${errorBody}` };
820
+ }
821
+
822
+ const data = await response.json();
823
+ const choice = data.choices?.[0];
824
+ const text = choice?.message?.content || "";
825
+ const reasoning = choice?.message?.reasoning_content || null;
826
+
827
+ return {
828
+ success: true,
829
+ text,
830
+ reasoning,
831
+ usage: data.usage || {},
832
+ };
833
+ } catch (err) {
834
+ return { success: false, error: "network_error", message: err.message };
835
+ }
836
+ }
837
+
838
+ /**
839
+ * Internal executor for Google Gemini REST API.
840
+ * @private
841
+ */
842
+ async _callGemini({ prompt, messages, system, model, apiKey, baseURL, temperature, json, maxTokens }) {
843
+ if (!apiKey) {
844
+ return { success: false, error: "missing_api_key", message: "GEMINI_API_KEY environment variable is not configured." };
845
+ }
846
+
847
+ const endpoint = `${baseURL.replace(/\/+$/, "")}/v1beta/models/${model}:generateContent?key=${apiKey}`;
848
+
849
+ const contents = [];
850
+ if (Array.isArray(messages) && messages.length > 0) {
851
+ for (const m of messages) {
852
+ const role = m.role === "assistant" || m.role === "model" ? "model" : "user";
853
+ contents.push({ role, parts: [{ text: m.content }] });
854
+ }
855
+ } else {
856
+ contents.push({ role: "user", parts: [{ text: prompt }] });
857
+ }
858
+
859
+ const body = {
860
+ contents,
861
+ generationConfig: {
862
+ temperature,
863
+ },
864
+ };
865
+
866
+ if (system) {
867
+ body.systemInstruction = {
868
+ parts: [{ text: system }],
869
+ };
870
+ }
871
+ if (json) {
872
+ body.generationConfig.responseMimeType = "application/json";
873
+ }
874
+ if (maxTokens) {
875
+ body.generationConfig.maxOutputTokens = maxTokens;
876
+ }
877
+
878
+ try {
879
+ const response = await fetch(endpoint, {
880
+ method: "POST",
881
+ headers: { "Content-Type": "application/json" },
882
+ body: JSON.stringify(body),
883
+ });
884
+
885
+ if (!response.ok) {
886
+ const errorBody = await response.text();
887
+ return { success: false, error: "provider_error", message: `Gemini Error (${response.status}): ${errorBody}` };
888
+ }
889
+
890
+ const data = await response.json();
891
+ const candidate = data.candidates?.[0];
892
+ const text = candidate?.content?.parts?.[0]?.text || "";
893
+
894
+ return {
895
+ success: true,
896
+ text,
897
+ usage: {
898
+ prompt_tokens: data.usageMetadata?.promptTokenCount || 0,
899
+ completion_tokens: data.usageMetadata?.candidatesTokenCount || 0,
900
+ total_tokens: data.usageMetadata?.totalTokenCount || 0,
901
+ },
902
+ };
903
+ } catch (err) {
904
+ return { success: false, error: "network_error", message: err.message };
905
+ }
906
+ }
907
+
908
+ /**
909
+ * Internal executor for OpenAI-compatible REST API.
910
+ * @private
911
+ */
912
+ async _callOpenAI({ prompt, messages, system, model, apiKey, baseURL, temperature, json, maxTokens }) {
913
+ if (!apiKey) {
914
+ return { success: false, error: "missing_api_key", message: "OPENAI_API_KEY environment variable is not configured." };
915
+ }
916
+
917
+ const endpoint = `${baseURL.replace(/\/+$/, "")}/chat/completions`;
918
+ const formattedMessages = [];
919
+ if (system) {
920
+ formattedMessages.push({ role: "system", content: system });
921
+ }
922
+ if (Array.isArray(messages) && messages.length > 0) {
923
+ formattedMessages.push(...messages);
924
+ } else {
925
+ formattedMessages.push({ role: "user", content: prompt });
926
+ }
927
+
928
+ const body = {
929
+ model,
930
+ messages: formattedMessages,
931
+ temperature,
932
+ };
933
+ if (json) {
934
+ body.response_format = { type: "json_object" };
935
+ }
936
+ if (maxTokens) {
937
+ body.max_tokens = maxTokens;
938
+ }
939
+
940
+ try {
941
+ const response = await fetch(endpoint, {
942
+ method: "POST",
943
+ headers: {
944
+ "Content-Type": "application/json",
945
+ Authorization: `Bearer ${apiKey}`,
946
+ },
947
+ body: JSON.stringify(body),
948
+ });
949
+
950
+ if (!response.ok) {
951
+ const errorBody = await response.text();
952
+ return { success: false, error: "provider_error", message: `OpenAI Error (${response.status}): ${errorBody}` };
953
+ }
954
+
955
+ const data = await response.json();
956
+ const choice = data.choices?.[0];
957
+ const text = choice?.message?.content || "";
958
+
959
+ return {
960
+ success: true,
961
+ text,
962
+ usage: data.usage || {},
963
+ };
964
+ } catch (err) {
965
+ return { success: false, error: "network_error", message: err.message };
966
+ }
967
+ }
968
+
969
+ /**
970
+ * Creates an Express rate-limiting middleware for AI routes.
971
+ * @param {Object} [options={}]
972
+ * @returns {Function} Express middleware.
973
+ */
974
+ middleware(options = {}) {
975
+ return (req, res, next) => {
976
+ const clientIp = getClientIp(req);
977
+ const rateCheck = this.checkRateLimit(clientIp, options.rateLimit || this.rateLimit);
978
+
979
+ if (!rateCheck.allowed) {
980
+ res.setHeader("Retry-After", String(rateCheck.retryAfter));
981
+ return res.status(429).json({
982
+ status: "error",
983
+ error: "rate_limit_exceeded",
984
+ message: options.message || "Rate limit exceeded. Please try again later.",
985
+ retryAfter: rateCheck.retryAfter,
986
+ });
987
+ }
988
+
989
+ next();
990
+ };
991
+ }
992
+
993
+ /**
994
+ * Alias for middleware().
995
+ * @param {Object} [options={}]
996
+ * @returns {Function} Express middleware.
997
+ */
998
+ protect(options = {}) {
999
+ return this.middleware(options);
1000
+ }
1001
+
1002
+ /**
1003
+ * Static helper to retrieve client IP from request.
1004
+ * @param {import('express').Request|Object} req
1005
+ * @returns {string}
1006
+ */
1007
+ static getClientIp(req) {
1008
+ return getClientIp(req);
1009
+ }
1010
+
1011
+ /**
1012
+ * Static helper for sensitive PII data masking.
1013
+ * @param {string} prompt
1014
+ * @param {Object} [data=null]
1015
+ * @param {string[]} [sensitiveKeys=[]]
1016
+ * @returns {{ maskedPrompt: string, maskedData: Object|null, tokenMap: Object, reverseTokenMap: Object }}
1017
+ */
1018
+ static mask(prompt, data = null, sensitiveKeys = []) {
1019
+ return maskSensitiveData(prompt, data, sensitiveKeys);
1020
+ }
1021
+
1022
+ /**
1023
+ * Static helper to unmask sensitive PII tokens back to original values.
1024
+ * @param {string} text
1025
+ * @param {Object} reverseTokenMap
1026
+ * @returns {string}
1027
+ */
1028
+ static unmask(text, reverseTokenMap) {
1029
+ return unmaskSensitiveData(text, reverseTokenMap);
1030
+ }
1031
+
1032
+ /**
1033
+ * Static factory method to create an Express middleware.
1034
+ * @param {Object} [options={}]
1035
+ * @returns {Function}
1036
+ */
1037
+ static protect(options = {}) {
1038
+ const aiInstance = new AI(options);
1039
+ return aiInstance.middleware(options);
1040
+ }
1041
+
1042
+ /**
1043
+ * Resets all in-memory rate limiting counters.
1044
+ */
1045
+ static resetRateLimits() {
1046
+ aiRateBuckets.clear();
1047
+ }
1048
+ }
1049
+
1050
+ export const ai = new AI();
1051
+ export default AI;