@windrun-huaiin/backend-core 15.1.0 → 17.0.0

package/src/index.ts

@@ -3,4 +3,5 @@ export * from './services/database';
 export * from './services/aggregate';
 export * from './services/context';
 export * from './services/stripe';
+export * from './services/ai';
 export * from './lib';

package/src/lib/upstash/qstash.ts

@@ -46,63 +46,103 @@ const getReceiver = (): Receiver | null => {
 
 export type PublishBody = Record<string, unknown> | string | number | boolean | null;
 
-export interface PublishMessageOptions {
+export interface QstashEnvelope<TBody extends PublishBody = PublishBody> {
+  source_msg_id: string;
+  payload: TBody;
+}
+
+export interface PublishMessageOptions<TBody extends PublishBody = PublishBody> {
   url: string;
-  body: PublishBody;
+  body: TBody;
 }
 
+const generateSourceMessageId = (): string => {
+  try {
+    return crypto.randomUUID();
+  } catch {
+    return `${Date.now()}_${Math.random().toString(16).slice(2)}`;
+  }
+};
+
+const createEnvelope = <TBody extends PublishBody>(body: TBody): QstashEnvelope<TBody> => {
+  return {
+    source_msg_id: generateSourceMessageId(),
+    payload: body,
+  };
+};
+
 /**
  * Publish a message. Returns message id or null if QStash is unavailable.
  */
-export const publishMessage = async (options: PublishMessageOptions): Promise<string | null> => {
+export const publishMessage = async <TBody extends PublishBody>(
+  options: PublishMessageOptions<TBody>
+): Promise<{ messageId: string | null; message: QstashEnvelope<TBody> } | null> => {
+  const message = createEnvelope(options.body);
+
   return withQstash(async (client) => {
     const result = await (client as any).publishJSON({
       url: options.url,
-      body: options.body,
+      body: message,
     });
-    return typeof result === 'string' ? result : result?.messageId ?? null;
+    return {
+      messageId: typeof result === 'string' ? result : result?.messageId ?? null,
+      message,
+    };
   });
 };
 
 /**
  * Publish a delayed message. Returns message id or null if QStash is unavailable.
  */
-export const publishDelayedMessage = async (
-  options: PublishMessageOptions & { delaySec: number }
-): Promise<string | null> => {
+export const publishDelayedMessage = async <TBody extends PublishBody>(
+  options: PublishMessageOptions<TBody> & { delaySec: number }
+): Promise<{ messageId: string | null; message: QstashEnvelope<TBody> } | null> => {
+  const message = createEnvelope(options.body);
+
   return withQstash(async (client) => {
     const result = await (client as any).publishJSON({
       url: options.url,
-      body: options.body,
+      body: message,
       delay: options.delaySec,
     });
-    return typeof result === 'string' ? result : result?.messageId ?? null;
+    return {
+      messageId: typeof result === 'string' ? result : result?.messageId ?? null,
+      message,
+    };
   });
 };
 
-export interface ScheduleMessageOptions extends PublishMessageOptions {
+export interface ScheduleMessageOptions<TBody extends PublishBody = PublishBody>
+  extends PublishMessageOptions<TBody> {
   cron: string;
 }
 
 /**
  * Schedule a recurring message. Returns schedule id or null if QStash is unavailable.
  */
-export const scheduleMessage = async (options: ScheduleMessageOptions): Promise<string | null> => {
+export const scheduleMessage = async <TBody extends PublishBody>(
+  options: ScheduleMessageOptions<TBody>
+): Promise<{ scheduleId: string | null; message: QstashEnvelope<TBody> } | null> => {
+  const message = createEnvelope(options.body);
+
   return withQstash(async (client) => {
     const anyClient = client as any;
     const result =
       (await anyClient.schedules?.create?.({
         url: options.url,
-        body: options.body,
+        body: message,
         cron: options.cron,
       })) ??
       (await anyClient.publishJSON?.({
         url: options.url,
-        body: options.body,
+        body: message,
         cron: options.cron,
       }));
 
-    return typeof result === 'string' ? result : result?.scheduleId ?? result?.id ?? null;
+    return {
+      scheduleId: typeof result === 'string' ? result : result?.scheduleId ?? result?.id ?? null,
+      message,
+    };
   });
 };
 

package/src/lib/upstash/redis-structures.ts

@@ -1,5 +1,14 @@
+import type { Redis } from '@upstash/redis';
+
 import { withRedis } from '../upstash-config';
 
+export type RedisStringKeyValue = Record<string, string>;
+export type RedisJsonKeyValue<T> = Record<string, T>;
+export type RedisHashStringValue = Record<string, string>;
+export type RedisPipelineBuilder<TResult> = (pipeline: ReturnType<Redis['pipeline']>) => {
+  exec: () => Promise<TResult>;
+};
+
 /**
  * Set a plain string value with optional TTL (seconds).
  */
@@ -26,6 +35,34 @@ export const getString = async (key: string): Promise<string | null> => {
   return withRedis((redis) => redis.get<string>(key));
 };
 
+/**
+ * MGET plain string values. Missing keys are returned as null.
+ */
+export const mget = async (keys: string[]): Promise<(string | null)[] | null> => {
+  return withRedis((redis) => {
+    if (keys.length === 0) {
+      return [];
+    }
+
+    return redis.mget<(string | null)[]>(...keys);
+  });
+};
+
+/**
+ * MSET plain string values.
+ */
+export const mset = async (entries: RedisStringKeyValue): Promise<boolean> => {
+  const keys = Object.keys(entries);
+  if (keys.length === 0) {
+    return true;
+  }
+
+  return withRedis(async (redis) => {
+    await redis.mset(entries);
+    return true;
+  }).then((result) => result ?? false);
+};
+
 /**
  * Store an object as JSON string with optional TTL (seconds).
  */
@@ -64,6 +101,49 @@ export const getJson = async <T>(key: string): Promise<T | null> => {
   });
 };
 
+/**
+ * MGET JSON values stored as strings. Missing or invalid values are returned as null.
+ */
+export const mgetJson = async <T>(keys: string[]): Promise<(T | null)[] | null> => {
+  return withRedis(async (redis) => {
+    if (keys.length === 0) {
+      return [];
+    }
+
+    const payloads = await redis.mget<(string | null)[]>(...keys);
+    return payloads.map((payload) => {
+      if (!payload) {
+        return null;
+      }
+
+      try {
+        return JSON.parse(payload) as T;
+      } catch {
+        return null;
+      }
+    });
+  });
+};
+
+/**
+ * MSET JSON values as strings.
+ */
+export const msetJson = async <T>(entries: RedisJsonKeyValue<T>): Promise<boolean> => {
+  const keys = Object.keys(entries);
+  if (keys.length === 0) {
+    return true;
+  }
+
+  const payloads = Object.fromEntries(
+    Object.entries(entries).map(([key, value]) => [key, JSON.stringify(value)])
+  ) as RedisStringKeyValue;
+
+  return withRedis(async (redis) => {
+    await redis.mset(payloads);
+    return true;
+  }).then((result) => result ?? false);
+};
+
 /**
  * Delete a key. Returns false if Redis is unavailable.
  */
@@ -75,6 +155,52 @@ export const deleteKey = async (key: string): Promise<boolean> => {
   return result ?? false;
 };
 
+/**
+ * DEL multiple keys. Returns deleted count, or null if Redis is unavailable.
+ */
+export const del = async (keys: string[]): Promise<number | null> => {
+  return withRedis((redis) => {
+    if (keys.length === 0) {
+      return 0;
+    }
+
+    return redis.del(...keys);
+  });
+};
+
+/**
+ * EXISTS a key.
+ */
+export const exists = async (key: string): Promise<boolean | null> => {
+  return withRedis(async (redis) => {
+    const count = await redis.exists(key);
+    return count > 0;
+  });
+};
+
+/**
+ * EXPIRE a key in seconds.
+ */
+export const expire = async (key: string, ttlSec: number): Promise<boolean> => {
+  if (ttlSec <= 0) {
+    return false;
+  }
+
+  const result = await withRedis(async (redis) => {
+    const changed = await redis.expire(key, ttlSec);
+    return changed > 0;
+  });
+
+  return result ?? false;
+};
+
+/**
+ * TTL for a key in seconds. Returns null if Redis is unavailable.
+ */
+export const ttl = async (key: string): Promise<number | null> => {
+  return withRedis((redis) => redis.ttl(key));
+};
+
 /**
  * Set a hash field value.
  */
@@ -93,6 +219,42 @@ export const getHashField = async (key: string, field: string): Promise<string |
   return withRedis((redis) => redis.hget<string>(key, field));
 };
 
+/**
+ * HMSET hash fields.
+ */
+export const hmset = async (key: string, values: RedisHashStringValue): Promise<boolean> => {
+  const fields = Object.keys(values);
+  if (fields.length === 0) {
+    return true;
+  }
+
+  const result = await withRedis(async (redis) => {
+    await redis.hset(key, values);
+    return true;
+  });
+  return result ?? false;
+};
+
+/**
+ * HMGET hash fields.
+ */
+export const hmget = async (
+  key: string,
+  fields: string[]
+): Promise<Record<string, string | null> | null> => {
+  return withRedis(async (redis) => {
+    if (fields.length === 0) {
+      return {};
+    }
+
+    const result = await redis.hmget<Record<string, string | null>>(key, ...fields);
+    if (!result) {
+      return Object.fromEntries(fields.map((field) => [field, null]));
+    }
+    return result;
+  });
+};
+
 /**
  * Store a hash field as JSON string.
  */
@@ -137,6 +299,30 @@ export const getHashAll = async (key: string): Promise<Record<string, string> |
   });
 };
 
+/**
+ * HEXISTS a hash field.
+ */
+export const hexists = async (key: string, field: string): Promise<boolean | null> => {
+  return withRedis(async (redis) => {
+    const exists = await redis.hexists(key, field);
+    return exists > 0;
+  });
+};
+
+/**
+ * HKEYS for a hash.
+ */
+export const hkeys = async (key: string): Promise<string[] | null> => {
+  return withRedis((redis) => redis.hkeys(key));
+};
+
+/**
+ * HLEN for a hash.
+ */
+export const hlen = async (key: string): Promise<number | null> => {
+  return withRedis((redis) => redis.hlen(key));
+};
+
 /**
  * Remove a hash field.
  */
@@ -148,6 +334,56 @@ export const deleteHashField = async (key: string, field: string): Promise<boole
   return result ?? false;
 };
 
+/**
+ * SADD members to a set. Returns count of newly added members, or null if Redis is unavailable.
+ */
+export const sadd = async (key: string, members: string[]): Promise<number | null> => {
+  return withRedis((redis) => {
+    if (members.length === 0) {
+      return 0;
+    }
+
+    return redis.sadd(key, members[0], ...members.slice(1));
+  });
+};
+
+/**
+ * SREM members from a set. Returns count of removed members, or null if Redis is unavailable.
+ */
+export const srem = async (key: string, members: string[]): Promise<number | null> => {
+  return withRedis((redis) => {
+    if (members.length === 0) {
+      return 0;
+    }
+
+    return redis.srem(key, ...members);
+  });
+};
+
+/**
+ * SISMEMBER for a set member.
+ */
+export const sismember = async (key: string, member: string): Promise<boolean | null> => {
+  return withRedis(async (redis) => {
+    const exists = await redis.sismember(key, member);
+    return exists > 0;
+  });
+};
+
+/**
+ * SMEMBERS for a set.
+ */
+export const smembers = async (key: string): Promise<string[] | null> => {
+  return withRedis((redis) => redis.smembers<string[]>(key));
+};
+
+/**
+ * SCARD for a set.
+ */
+export const scard = async (key: string): Promise<number | null> => {
+  return withRedis((redis) => redis.scard(key));
+};
+
 type ListDirection = 'left' | 'right';
 
 /**
@@ -198,3 +434,15 @@ export const rangeList = async (
 export const listLength = async (key: string): Promise<number | null> => {
   return withRedis((redis) => redis.llen(key));
 };
+
+/**
+ * Execute a Redis pipeline and return the result array from exec().
+ */
+export const pipeline = async <TResult>(
+  build: RedisPipelineBuilder<TResult>
+): Promise<TResult | null> => {
+  return withRedis(async (redis) => {
+    const pipeline = redis.pipeline();
+    return build(pipeline).exec();
+  });
+};

package/src/lib/upstash-config.ts

@@ -19,6 +19,7 @@ let qstashWarnedHealthSchedule = false;
 
 let redisHealthTimer: ReturnType<typeof setTimeout> | null = null;
 let qstashHealthTimer: ReturnType<typeof setTimeout> | null = null;
+let cachedRedisPrefixed: Redis | null = null;
 
 const isNonEmpty = (value: string | undefined): value is string =>
   typeof value === 'string' && value.trim().length > 0;
@@ -32,6 +33,105 @@ const isValidUrl = (value: string): boolean => {
   }
 };
 
+const getRequiredRedisAppName = (): string => {
+  const appName = process.env.NEXT_PUBLIC_APP_NAME;
+  if (!isNonEmpty(appName)) {
+    throw new Error(
+      '[Upstash Config] NEXT_PUBLIC_APP_NAME is required for Redis key prefixing and must not be empty'
+    );
+  }
+
+  const normalized = appName.replace(/\s+/g, '').toLowerCase();
+  if (!normalized) {
+    throw new Error(
+      '[Upstash Config] NEXT_PUBLIC_APP_NAME must contain non-whitespace characters for Redis key prefixing'
+    );
+  }
+
+  return normalized;
+};
+
+const getRedisKeyPrefix = (): string => {
+  const envSuffix = process.env.NODE_ENV === 'production' ? 'live' : 'test';
+  return `${getRequiredRedisAppName()}_${envSuffix}`;
+};
+
+const prefixRedisKey = (prefix: string, key: string): string => `${prefix}:${key}`;
+
+const prefixRedisKeys = (prefix: string, keys: string[]): string[] =>
+  keys.map((key) => prefixRedisKey(prefix, key));
+
+const prefixFirstStringArg = (args: unknown[], prefix: string): unknown[] => {
+  if (typeof args[0] !== 'string') {
+    return args;
+  }
+
+  const nextArgs = [...args];
+  nextArgs[0] = prefixRedisKey(prefix, args[0]);
+  return nextArgs;
+};
+
+const prefixAllStringArgs = (args: unknown[], prefix: string): unknown[] => {
+  return args.map((arg) => (typeof arg === 'string' ? prefixRedisKey(prefix, arg) : arg));
+};
+
+const keyArrayCommands = new Set(['mget', 'del']);
+const allStringKeyCommands = new Set(['exists']);
+
+const createPrefixedPipeline = <T extends object>(target: T, prefix: string): T => {
+  return new Proxy(target, {
+    get(obj, prop, receiver) {
+      const value = Reflect.get(obj, prop, receiver);
+      if (typeof value !== 'function') {
+        return value;
+      }
+
+      return (...args: unknown[]) => {
+        if (prop === 'eval' || prop === 'evalsha' || prop === 'evalro' || prop === 'evalshaRo') {
+          const [script, keys, argv] = args as [string, string[], unknown[]];
+          return (value as (...innerArgs: unknown[]) => unknown).call(
+            obj,
+            script,
+            prefixRedisKeys(prefix, keys),
+            argv
+          );
+        }
+
+        if (prop === 'pipeline' || prop === 'multi') {
+          const nested = (value as (...innerArgs: unknown[]) => unknown).call(obj);
+          return createPrefixedPipeline(nested as T, prefix);
+        }
+
+        if (typeof prop === 'string' && keyArrayCommands.has(prop)) {
+          const nextArgs = prefixAllStringArgs(args, prefix);
+          return (value as (...innerArgs: unknown[]) => unknown).apply(obj, nextArgs);
+        }
+
+        if (typeof prop === 'string' && allStringKeyCommands.has(prop)) {
+          const nextArgs = prefixAllStringArgs(args, prefix);
+          return (value as (...innerArgs: unknown[]) => unknown).apply(obj, nextArgs);
+        }
+
+        if (prop === 'mset') {
+          const [entries] = args as [Record<string, unknown>];
+          const prefixedEntries = Object.fromEntries(
+            Object.entries(entries).map(([key, entryValue]) => [prefixRedisKey(prefix, key), entryValue])
+          );
+          return (value as (...innerArgs: unknown[]) => unknown).call(obj, prefixedEntries);
+        }
+
+        if (prop === 'hmget') {
+          const nextArgs = prefixFirstStringArg(args, prefix);
+          return (value as (...innerArgs: unknown[]) => unknown).apply(obj, nextArgs);
+        }
+
+        const nextArgs = prefixFirstStringArg(args, prefix);
+        return (value as (...innerArgs: unknown[]) => unknown).apply(obj, nextArgs);
+      };
+    },
+  });
+};
+
 const parseMinutes = (value: string | undefined, fallback: number): number => {
   if (!isNonEmpty(value)) {
     return fallback;
@@ -138,12 +238,12 @@ const scheduleQstashHealthCheck = (token: string): void => {
  * - read-through cached instance only
  */
 export const getRedis = (): Redis | null => {
-  return cachedRedis;
+  return cachedRedisPrefixed;
 };
 
 const ensureRedis = async (): Promise<Redis | null> => {
-  if (cachedRedis) {
-    return cachedRedis;
+  if (cachedRedisPrefixed) {
+    return cachedRedisPrefixed;
   }
   if (redisInitPromise) {
     return redisInitPromise;
@@ -170,14 +270,16 @@ const ensureRedis = async (): Promise<Redis | null> => {
     }
 
     try {
+      const keyPrefix = getRedisKeyPrefix();
       const client = new Redis({
         url: UPSTASH_REDIS_REST_URL,
         token: UPSTASH_REDIS_REST_TOKEN,
       });
       await client.ping();
       cachedRedis = client;
+      cachedRedisPrefixed = createPrefixedPipeline(client, keyPrefix) as Redis;
       scheduleRedisHealthCheck();
-      return cachedRedis;
+      return cachedRedisPrefixed;
     } catch (error) {
       if (!redisWarnedInitError) {
         redisWarnedInitError = true;

package/src/services/ai/abort.ts

@@ -0,0 +1,26 @@
+export function createUpstreamAbortSignal(requestSignal: AbortSignal, timeoutMs: number) {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort('timeout'), timeoutMs);
+
+  const forwardAbort = () => {
+    clearTimeout(timeoutId);
+    controller.abort(requestSignal.reason ?? 'request_aborted');
+  };
+
+  if (requestSignal.aborted) {
+    forwardAbort();
+  } else {
+    requestSignal.addEventListener('abort', forwardAbort, { once: true });
+  }
+
+  controller.signal.addEventListener(
+    'abort',
+    () => {
+      clearTimeout(timeoutId);
+      requestSignal.removeEventListener('abort', forwardAbort);
+    },
+    { once: true },
+  );
+
+  return controller.signal;
+}