@openclaw/zalouser 2026.3.13 → 2026.5.1-beta.2

package/src/zalo-js.ts

@@ -1,11 +1,15 @@
 import { randomUUID } from "node:crypto";
 import fs from "node:fs";
-import fsp from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
-import { loadOutboundMediaFromUrl } from "openclaw/plugin-sdk/zalouser";
+import { loadOutboundMediaFromUrl } from "openclaw/plugin-sdk/outbound-media";
+import { resolveStateDir as resolvePluginStateDir } from "openclaw/plugin-sdk/state-paths";
+import {
+  normalizeLowercaseStringOrEmpty,
+  normalizeOptionalLowercaseString,
+  normalizeOptionalString,
+} from "openclaw/plugin-sdk/text-runtime";
 import { normalizeZaloReactionIcon } from "./reaction.js";
-import { getZalouserRuntime } from "./runtime.js";
 import type {
   ZaloAuthStatus,
   ZaloEventMessage,
@@ -19,17 +23,16 @@ import type {
   ZcaUserInfo,
 } from "./types.js";
 import {
-  LoginQRCallbackEventType,
   TextStyle,
-  ThreadType,
-  Zalo,
   type API,
   type Credentials,
   type GroupInfo,
   type LoginQRCallbackEvent,
   type Message,
   type User,
+  createZalo,
 } from "./zca-client.js";
+import { LoginQRCallbackEventType, ThreadType } from "./zca-constants.js";
 
 const API_LOGIN_TIMEOUT_MS = 20_000;
 const QR_LOGIN_TTL_MS = 3 * 60_000;
@@ -43,6 +46,7 @@ const LISTENER_WATCHDOG_MAX_GAP_MS = 35_000;
 
 const apiByProfile = new Map<string, API>();
 const apiInitByProfile = new Map<string, Promise<API>>();
+const credentialSignaturesByProfile = new Map<string, string>();
 
 type ActiveZaloQrLogin = {
   id: string;
@@ -85,7 +89,7 @@ type StoredZaloCredentials = {
 };
 
 function resolveStateDir(env: NodeJS.ProcessEnv = process.env): string {
-  return getZalouserRuntime().state.resolveStateDir(env, os.homedir);
+  return resolvePluginStateDir(env, os.homedir);
 }
 
 function resolveCredentialsDir(env: NodeJS.ProcessEnv = process.env): string {
@@ -93,7 +97,7 @@ function resolveCredentialsDir(env: NodeJS.ProcessEnv = process.env): string {
 }
 
 function credentialsFilename(profile: string): string {
-  const trimmed = profile.trim().toLowerCase();
+  const trimmed = normalizeLowercaseStringOrEmpty(profile);
   if (!trimmed || trimmed === "default") {
     return "credentials.json";
   }
@@ -104,6 +108,82 @@ function resolveCredentialsPath(profile: string, env: NodeJS.ProcessEnv = proces
   return path.join(resolveCredentialsDir(env), credentialsFilename(profile));
 }
 
+function isNodeErrorCode(error: unknown, code: string): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "code" in error &&
+    (error as { code?: unknown }).code === code
+  );
+}
+
+function ensureCredentialsDir(): string {
+  const dir = resolveCredentialsDir();
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const stat = fs.lstatSync(dir);
+  if (!stat.isDirectory() || stat.isSymbolicLink()) {
+    throw new Error("Refusing to use non-directory Zalo credentials path");
+  }
+  try {
+    fs.chmodSync(dir, 0o700);
+  } catch {
+    // Best-effort on platforms that support POSIX permissions.
+  }
+  return dir;
+}
+
+function isReadableCredentialFile(filePath: string): boolean {
+  try {
+    const stat = fs.lstatSync(filePath);
+    return stat.isFile() && !stat.isSymbolicLink();
+  } catch (error) {
+    if (isNodeErrorCode(error, "ENOENT")) {
+      return false;
+    }
+    throw error;
+  }
+}
+
+function assertWritableCredentialTarget(filePath: string): void {
+  try {
+    const stat = fs.lstatSync(filePath);
+    if (!stat.isFile() || stat.isSymbolicLink()) {
+      throw new Error("Refusing to write Zalo credentials to symlinked path");
+    }
+  } catch (error) {
+    if (isNodeErrorCode(error, "ENOENT")) {
+      return;
+    }
+    throw error;
+  }
+}
+
+function writeCredentialFileAtomic(filePath: string, payload: string): void {
+  const dir = ensureCredentialsDir();
+  assertWritableCredentialTarget(filePath);
+  const tempPath = path.join(dir, `.${path.basename(filePath)}.tmp-${process.pid}-${randomUUID()}`);
+  try {
+    fs.writeFileSync(tempPath, payload, { encoding: "utf-8", mode: 0o600, flag: "wx" });
+    try {
+      fs.chmodSync(tempPath, 0o600);
+    } catch {
+      // Best-effort on platforms that support POSIX permissions.
+    }
+    fs.renameSync(tempPath, filePath);
+    try {
+      fs.chmodSync(filePath, 0o600);
+    } catch {
+      // Best-effort on platforms that support POSIX permissions.
+    }
+  } finally {
+    try {
+      fs.unlinkSync(tempPath);
+    } catch {
+      // The temp file is normally moved by renameSync.
+    }
+  }
+}
+
 function withTimeout<T>(promise: Promise<T>, timeoutMs: number, label: string): Promise<T> {
   return new Promise((resolve, reject) => {
     const timer = setTimeout(() => {
@@ -204,14 +284,17 @@ function normalizeAccountInfoUser(info: AccountInfoResponse): User | null {
     }
     return null;
   }
-  return info as User;
+  return info;
 }
 
 function toInteger(value: unknown, fallback = 0): number {
   if (typeof value === "number" && Number.isFinite(value)) {
     return Math.trunc(value);
   }
-  const parsed = Number.parseInt(String(value ?? ""), 10);
+  const parsed = Number.parseInt(
+    typeof value === "string" ? value : typeof value === "number" ? String(value) : "",
+    10,
+  );
   if (!Number.isFinite(parsed)) {
     return fallback;
   }
@@ -244,7 +327,10 @@ function resolveInboundTimestamp(rawTs: unknown): number {
   if (typeof rawTs === "number" && Number.isFinite(rawTs)) {
     return rawTs > 1_000_000_000_000 ? rawTs : rawTs * 1000;
   }
-  const parsed = Number.parseInt(String(rawTs ?? ""), 10);
+  const parsed = Number.parseInt(
+    typeof rawTs === "string" ? rawTs : typeof rawTs === "number" ? String(rawTs) : "",
+    10,
+  );
   if (!Number.isFinite(parsed) || parsed <= 0) {
     return Date.now();
   }
@@ -489,13 +575,13 @@ function resolveUploadedVoiceAsset(
     if (!item || typeof item !== "object") {
       continue;
     }
-    const fileType = item.fileType?.toLowerCase();
+    const fileType = normalizeOptionalLowercaseString(item.fileType);
     const fileUrl = item.fileUrl?.trim();
     if (!fileUrl) {
       continue;
     }
     if (fileType === "others" || fileType === "video") {
-      return { fileUrl, fileName: item.fileName?.trim() || undefined };
+      return { fileUrl, fileName: normalizeOptionalString(item.fileName) };
     }
   }
   return undefined;
@@ -509,8 +595,8 @@ function buildZaloVoicePlaybackUrl(asset: { fileUrl: string; fileName?: string }
 
 function mapFriend(friend: User): ZcaFriend {
   return {
-    userId: String(friend.userId),
-    displayName: friend.displayName || friend.zaloName || friend.username || String(friend.userId),
+    userId: friend.userId,
+    displayName: friend.displayName || friend.zaloName || friend.username || friend.userId,
     avatar: friend.avatar || undefined,
   };
 }
@@ -521,8 +607,8 @@ function mapGroup(groupId: string, group: GroupInfo & Record<string, unknown>):
       ? group.totalMember
       : undefined;
   return {
-    groupId: String(groupId),
-    name: group.name?.trim() || String(groupId),
+    groupId,
+    name: group.name?.trim() || groupId,
     memberCount: totalMember,
   };
 }
@@ -530,7 +616,7 @@ function mapGroup(groupId: string, group: GroupInfo & Record<string, unknown>):
 function readCredentials(profile: string): StoredZaloCredentials | null {
   const filePath = resolveCredentialsPath(profile);
   try {
-    if (!fs.existsSync(filePath)) {
+    if (!isReadableCredentialFile(filePath)) {
       return null;
     }
     const raw = fs.readFileSync(filePath, "utf-8");
@@ -544,7 +630,7 @@ function readCredentials(profile: string): StoredZaloCredentials | null {
     ) {
       return null;
     }
-    return {
+    const credentials = {
       imei: parsed.imei,
       cookie: parsed.cookie as Credentials["cookie"],
       userAgent: parsed.userAgent,
@@ -552,31 +638,73 @@ function readCredentials(profile: string): StoredZaloCredentials | null {
       createdAt: typeof parsed.createdAt === "string" ? parsed.createdAt : new Date().toISOString(),
       lastUsedAt: typeof parsed.lastUsedAt === "string" ? parsed.lastUsedAt : undefined,
     };
+    credentialSignaturesByProfile.set(profile, credentialSignature(credentials));
+    return credentials;
   } catch {
     return null;
   }
 }
 
-function touchCredentials(profile: string): void {
-  const existing = readCredentials(profile);
-  if (!existing) {
-    return;
+function credentialSignature(
+  credentials: Omit<StoredZaloCredentials, "createdAt" | "lastUsedAt">,
+): string {
+  return JSON.stringify({
+    imei: credentials.imei,
+    cookie: canonicalCredentialCookie(credentials.cookie),
+    userAgent: credentials.userAgent,
+    language: credentials.language,
+  });
+}
+
+function stableCanonicalValue(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map(stableCanonicalValue);
   }
-  const next: StoredZaloCredentials = {
-    ...existing,
-    lastUsedAt: new Date().toISOString(),
-  };
-  const dir = resolveCredentialsDir();
-  fs.mkdirSync(dir, { recursive: true });
-  fs.writeFileSync(resolveCredentialsPath(profile), JSON.stringify(next, null, 2), "utf-8");
+  if (!value || typeof value !== "object") {
+    return value;
+  }
+  return Object.fromEntries(
+    Object.entries(value as Record<string, unknown>)
+      .toSorted(([left], [right]) => left.localeCompare(right))
+      .map(([key, entry]) => [key, stableCanonicalValue(entry)]),
+  );
+}
+
+function stableSignatureValue(value: unknown): string {
+  return JSON.stringify(stableCanonicalValue(value)) ?? "undefined";
+}
+
+function canonicalCookieArray(value: unknown[]): unknown[] {
+  return value
+    .map(stableCanonicalValue)
+    .toSorted((left, right) =>
+      stableSignatureValue(left).localeCompare(stableSignatureValue(right)),
+    );
+}
+
+function canonicalCredentialCookie(cookie: Credentials["cookie"]): unknown {
+  if (Array.isArray(cookie)) {
+    return canonicalCookieArray(cookie);
+  }
+  if (!cookie || typeof cookie !== "object") {
+    return cookie;
+  }
+  return Object.fromEntries(
+    Object.entries(cookie as Record<string, unknown>)
+      .toSorted(([left], [right]) => left.localeCompare(right))
+      .map(([key, entry]) => [
+        key,
+        key === "cookies" && Array.isArray(entry)
+          ? canonicalCookieArray(entry)
+          : stableCanonicalValue(entry),
+      ]),
+  );
 }
 
 function writeCredentials(
   profile: string,
   credentials: Omit<StoredZaloCredentials, "createdAt" | "lastUsedAt">,
 ): void {
-  const dir = resolveCredentialsDir();
-  fs.mkdirSync(dir, { recursive: true });
   const existing = readCredentials(profile);
   const now = new Date().toISOString();
   const next: StoredZaloCredentials = {
@@ -584,7 +712,59 @@ function writeCredentials(
     createdAt: existing?.createdAt ?? now,
     lastUsedAt: now,
   };
-  fs.writeFileSync(resolveCredentialsPath(profile), JSON.stringify(next, null, 2), "utf-8");
+  writeCredentialFileAtomic(resolveCredentialsPath(profile), JSON.stringify(next, null, 2));
+  credentialSignaturesByProfile.set(profile, credentialSignature(next));
+}
+
+function snapshotApiCredentials(
+  api: API,
+  fallback?: Partial<Omit<StoredZaloCredentials, "createdAt" | "lastUsedAt">>,
+): Omit<StoredZaloCredentials, "createdAt" | "lastUsedAt"> {
+  const ctx = api.getContext();
+  const cookieJson = api.getCookie().toJSON();
+  const refreshedCookies =
+    Array.isArray(cookieJson?.cookies) && cookieJson.cookies.length > 0
+      ? cookieJson.cookies
+      : fallback?.cookie;
+  const imei = normalizeOptionalString(ctx.imei) ?? normalizeOptionalString(fallback?.imei);
+  const userAgent =
+    normalizeOptionalString(ctx.userAgent) ?? normalizeOptionalString(fallback?.userAgent);
+  if (!imei || !refreshedCookies || !userAgent) {
+    throw new Error("Zalo API session did not expose refreshed credentials");
+  }
+  return {
+    imei,
+    cookie: refreshedCookies as Credentials["cookie"],
+    userAgent,
+    language: normalizeOptionalString(ctx.language) ?? normalizeOptionalString(fallback?.language),
+  };
+}
+
+function writeApiCredentials(
+  profile: string,
+  api: API,
+  fallback?: Partial<Omit<StoredZaloCredentials, "createdAt" | "lastUsedAt">>,
+): void {
+  writeCredentials(profile, snapshotApiCredentials(api, fallback));
+}
+
+function writeApiCredentialsIfChanged(profile: string, api: API): boolean {
+  const credentials = snapshotApiCredentials(api);
+  const signature = credentialSignature(credentials);
+  if (credentialSignaturesByProfile.get(profile) === signature) {
+    return false;
+  }
+  writeCredentials(profile, credentials);
+  return true;
+}
+
+function persistApiCredentialsIfChanged(profile: string, api: API): void {
+  try {
+    writeApiCredentialsIfChanged(profile, api);
+  } catch {
+    // Do not fail an already-successful Zalo operation only because the
+    // best-effort session refresh could not be persisted.
+  }
 }
 
 function clearCredentials(profile: string): boolean {
@@ -592,6 +772,7 @@ function clearCredentials(profile: string): boolean {
   try {
     if (fs.existsSync(filePath)) {
       fs.unlinkSync(filePath);
+      credentialSignaturesByProfile.delete(profile);
       return true;
     }
   } catch {
@@ -618,9 +799,9 @@ async function ensureApi(
   const initPromise = (async () => {
     const stored = readCredentials(profile);
     if (!stored) {
-      throw new Error(`No saved Zalo session for profile \"${profile}\"`);
+      throw new Error(`No saved Zalo session for profile "${profile}"`);
     }
-    const zalo = new Zalo({
+    const zalo = await createZalo({
       logging: false,
       selfListen: false,
     });
@@ -632,10 +813,10 @@ async function ensureApi(
         language: stored.language,
       }),
       timeoutMs,
-      `Timed out restoring Zalo session for profile \"${profile}\"`,
+      `Timed out restoring Zalo session for profile "${profile}"`,
     );
     apiByProfile.set(profile, api);
-    touchCredentials(profile);
+    writeApiCredentials(profile, api, stored);
     return api;
   })();
 
@@ -650,6 +831,23 @@ async function ensureApi(
   }
 }
 
+async function withZaloApi<T>(
+  profileInput: string | null | undefined,
+  operation: (api: API) => Promise<T>,
+  options: {
+    timeoutMs?: number;
+    shouldPersist?: (result: T) => boolean;
+  } = {},
+): Promise<T> {
+  const profile = normalizeProfile(profileInput);
+  const api = await ensureApi(profile, options.timeoutMs);
+  const result = await operation(api);
+  if (options.shouldPersist?.(result) ?? true) {
+    persistApiCredentialsIfChanged(profile, api);
+  }
+  return result;
+}
+
 function invalidateApi(profileInput?: string | null): void {
   const profile = normalizeProfile(profileInput);
   const api = apiByProfile.get(profile);
@@ -777,7 +975,7 @@ function extractGroupMembersFromInfo(
 }
 
 function toInboundMessage(message: Message, ownUserId?: string): ZaloInboundMessage | null {
-  const data = message.data as Record<string, unknown>;
+  const data = message.data;
   const isGroup = message.type === ThreadType.Group;
   const senderId = toNumberId(data.uidFrom);
   const threadId = isGroup
@@ -827,7 +1025,7 @@ function toInboundMessage(message: Message, ownUserId?: string): ZaloInboundMess
   };
 }
 
-export function zalouserSessionExists(profileInput?: string | null): boolean {
+function zalouserSessionExists(profileInput?: string | null): boolean {
   const profile = normalizeProfile(profileInput);
   return readCredentials(profile) !== null;
 }
@@ -838,8 +1036,12 @@ export async function checkZaloAuthenticated(profileInput?: string | null): Prom
     return false;
   }
   try {
-    const api = await ensureApi(profile, 12_000);
-    await withTimeout(api.fetchAccountInfo(), 12_000, "Timed out checking Zalo session");
+    await withZaloApi(
+      profile,
+      async (api) =>
+        await withTimeout(api.fetchAccountInfo(), 12_000, "Timed out checking Zalo session"),
+      { timeoutMs: 12_000 },
+    );
     return true;
   } catch {
     invalidateApi(profile);
@@ -849,24 +1051,26 @@ export async function checkZaloAuthenticated(profileInput?: string | null): Prom
 
 export async function getZaloUserInfo(profileInput?: string | null): Promise<ZcaUserInfo | null> {
   const profile = normalizeProfile(profileInput);
-  const api = await ensureApi(profile);
-  const info = await api.fetchAccountInfo();
-  const user = normalizeAccountInfoUser(info);
-  if (!user?.userId) {
-    return null;
-  }
-  return {
-    userId: String(user.userId),
-    displayName: user.displayName || user.zaloName || String(user.userId),
-    avatar: user.avatar || undefined,
-  };
+  return await withZaloApi(profile, async (api) => {
+    const info = await api.fetchAccountInfo();
+    const user = normalizeAccountInfoUser(info);
+    if (!user?.userId) {
+      return null;
+    }
+    return {
+      userId: user.userId,
+      displayName: user.displayName || user.zaloName || user.userId,
+      avatar: user.avatar || undefined,
+    };
+  });
 }
 
 export async function listZaloFriends(profileInput?: string | null): Promise<ZcaFriend[]> {
   const profile = normalizeProfile(profileInput);
-  const api = await ensureApi(profile);
-  const friends = await api.getAllFriends();
-  return friends.map(mapFriend);
+  return await withZaloApi(profile, async (api) => {
+    const friends = await api.getAllFriends();
+    return friends.map(mapFriend);
+  });
 }
 
 export async function listZaloFriendsMatching(
@@ -874,42 +1078,43 @@ export async function listZaloFriendsMatching(
   query?: string | null,
 ): Promise<ZcaFriend[]> {
   const friends = await listZaloFriends(profileInput);
-  const q = query?.trim().toLowerCase();
+  const q = normalizeOptionalLowercaseString(query);
   if (!q) {
     return friends;
   }
   const scored = friends
     .map((friend) => {
-      const id = friend.userId.toLowerCase();
-      const name = friend.displayName.toLowerCase();
+      const id = normalizeLowercaseStringOrEmpty(friend.userId);
+      const name = normalizeLowercaseStringOrEmpty(friend.displayName);
       const exact = id === q || name === q;
       const includes = id.includes(q) || name.includes(q);
       return { friend, exact, includes };
     })
     .filter((entry) => entry.includes)
-    .sort((a, b) => Number(b.exact) - Number(a.exact));
+    .toSorted((a, b) => Number(b.exact) - Number(a.exact));
   return scored.map((entry) => entry.friend);
 }
 
 export async function listZaloGroups(profileInput?: string | null): Promise<ZaloGroup[]> {
   const profile = normalizeProfile(profileInput);
-  const api = await ensureApi(profile);
-  const allGroups = await api.getAllGroups();
-  const ids = Object.keys(allGroups.gridVerMap ?? {});
-  if (ids.length === 0) {
-    return [];
-  }
-  const details = await fetchGroupsByIds(api, ids);
-  const rows: ZaloGroup[] = [];
-  for (const id of ids) {
-    const info = details.get(id);
-    if (!info) {
-      rows.push({ groupId: id, name: id });
-      continue;
+  return await withZaloApi(profile, async (api) => {
+    const allGroups = await api.getAllGroups();
+    const ids = Object.keys(allGroups.gridVerMap ?? {});
+    if (ids.length === 0) {
+      return [];
     }
-    rows.push(mapGroup(id, info as GroupInfo & Record<string, unknown>));
-  }
-  return rows;
+    const details = await fetchGroupsByIds(api, ids);
+    const rows: ZaloGroup[] = [];
+    for (const id of ids) {
+      const info = details.get(id);
+      if (!info) {
+        rows.push({ groupId: id, name: id });
+        continue;
+      }
+      rows.push(mapGroup(id, info as GroupInfo & Record<string, unknown>));
+    }
+    return rows;
+  });
 }
 
 export async function listZaloGroupsMatching(
@@ -917,13 +1122,13 @@ export async function listZaloGroupsMatching(
   query?: string | null,
 ): Promise<ZaloGroup[]> {
   const groups = await listZaloGroups(profileInput);
-  const q = query?.trim().toLowerCase();
+  const q = normalizeOptionalLowercaseString(query);
   if (!q) {
     return groups;
   }
   return groups.filter((group) => {
-    const id = group.groupId.toLowerCase();
-    const name = group.name.toLowerCase();
+    const id = normalizeLowercaseStringOrEmpty(group.groupId);
+    const name = normalizeLowercaseStringOrEmpty(group.name);
     return id.includes(q) || name.includes(q);
   });
 }
@@ -933,69 +1138,72 @@ export async function listZaloGroupMembers(
   groupId: string,
 ): Promise<ZaloGroupMember[]> {
   const profile = normalizeProfile(profileInput);
-  const api = await ensureApi(profile);
-
-  const infoResponse = await api.getGroupInfo(groupId);
-  const groupInfo = infoResponse.gridInfoMap?.[groupId] as
-    | (GroupInfo & { memVerList?: unknown })
-    | undefined;
-  if (!groupInfo) {
-    return [];
-  }
-
-  const memberIds = Array.isArray(groupInfo.memberIds)
-    ? groupInfo.memberIds.map((id: unknown) => toNumberId(id)).filter(Boolean)
-    : [];
-  const memVerIds = Array.isArray(groupInfo.memVerList)
-    ? groupInfo.memVerList.map((id: unknown) => toNumberId(id)).filter(Boolean)
-    : [];
-  const currentMembers = Array.isArray(groupInfo.currentMems) ? groupInfo.currentMems : [];
-
-  const currentById = new Map<string, { displayName?: string; avatar?: string }>();
-  for (const member of currentMembers) {
-    const id = toNumberId(member?.id);
-    if (!id) {
-      continue;
+  return await withZaloApi(profile, async (api) => {
+    const infoResponse = await api.getGroupInfo(groupId);
+    const groupInfo = infoResponse.gridInfoMap?.[groupId] as
+      | (GroupInfo & { memVerList?: unknown })
+      | undefined;
+    if (!groupInfo) {
+      return [];
     }
-    currentById.set(id, {
-      displayName: member.dName?.trim() || member.zaloName?.trim() || undefined,
-      avatar: member.avatar || undefined,
-    });
-  }
 
-  const uniqueIds = Array.from(
-    new Set<string>([...memberIds, ...memVerIds, ...currentById.keys()]),
-  );
-
-  const profileMap = new Map<string, { displayName?: string; avatar?: string }>();
-  if (uniqueIds.length > 0) {
-    const profiles = await api.getGroupMembersInfo(uniqueIds);
-    const profileEntries = profiles.profiles as Record<
-      string,
-      {
-        id?: string;
-        displayName?: string;
-        zaloName?: string;
-        avatar?: string;
-      }
-    >;
-    for (const [rawId, profileValue] of Object.entries(profileEntries)) {
-      const id = toNumberId(rawId) || toNumberId((profileValue as { id?: unknown })?.id);
-      if (!id || !profileValue) {
+    const memberIds = Array.isArray(groupInfo.memberIds)
+      ? groupInfo.memberIds.map((id: unknown) => toNumberId(id)).filter(Boolean)
+      : [];
+    const memVerIds = Array.isArray(groupInfo.memVerList)
+      ? groupInfo.memVerList.map((id: unknown) => toNumberId(id)).filter(Boolean)
+      : [];
+    const currentMembers = Array.isArray(groupInfo.currentMems) ? groupInfo.currentMems : [];
+
+    const currentById = new Map<string, { displayName?: string; avatar?: string }>();
+    for (const member of currentMembers) {
+      const id = toNumberId(member?.id);
+      if (!id) {
         continue;
       }
-      profileMap.set(id, {
-        displayName: profileValue.displayName?.trim() || profileValue.zaloName?.trim() || undefined,
-        avatar: profileValue.avatar || undefined,
+      currentById.set(id, {
+        displayName:
+          normalizeOptionalString(member.dName) ?? normalizeOptionalString(member.zaloName),
+        avatar: member.avatar || undefined,
       });
     }
-  }
 
-  return uniqueIds.map((id) => ({
-    userId: id,
-    displayName: profileMap.get(id)?.displayName || currentById.get(id)?.displayName || id,
-    avatar: profileMap.get(id)?.avatar || currentById.get(id)?.avatar,
-  }));
+    const uniqueIds = Array.from(
+      new Set<string>([...memberIds, ...memVerIds, ...currentById.keys()]),
+    );
+
+    const profileMap = new Map<string, { displayName?: string; avatar?: string }>();
+    if (uniqueIds.length > 0) {
+      const profiles = await api.getGroupMembersInfo(uniqueIds);
+      const profileEntries = profiles.profiles as Record<
+        string,
+        {
+          id?: string;
+          displayName?: string;
+          zaloName?: string;
+          avatar?: string;
+        }
+      >;
+      for (const [rawId, profileValue] of Object.entries(profileEntries)) {
+        const id = toNumberId(rawId) || toNumberId((profileValue as { id?: unknown })?.id);
+        if (!id || !profileValue) {
+          continue;
+        }
+        profileMap.set(id, {
+          displayName:
+            normalizeOptionalString(profileValue.displayName) ??
+            normalizeOptionalString(profileValue.zaloName),
+          avatar: profileValue.avatar || undefined,
+        });
+      }
+    }
+
+    return uniqueIds.map((id) => ({
+      userId: id,
+      displayName: profileMap.get(id)?.displayName || currentById.get(id)?.displayName || id,
+      avatar: profileMap.get(id)?.avatar || currentById.get(id)?.avatar,
+    }));
+  });
 }
 
 export async function resolveZaloGroupContext(
@@ -1012,18 +1220,19 @@ export async function resolveZaloGroupContext(
     return cached;
   }
 
-  const api = await ensureApi(profile);
-  const response = await api.getGroupInfo(normalizedGroupId);
-  const groupInfo = response.gridInfoMap?.[normalizedGroupId] as
-    | (GroupInfo & { currentMems?: unknown[]; memVerList?: unknown[] })
-    | undefined;
-  const context: ZaloGroupContext = {
-    groupId: normalizedGroupId,
-    name: groupInfo?.name?.trim() || undefined,
-    members: extractGroupMembersFromInfo(groupInfo),
-  };
-  writeCachedGroupContext(profile, context);
-  return context;
+  return await withZaloApi(profile, async (api) => {
+    const response = await api.getGroupInfo(normalizedGroupId);
+    const groupInfo = response.gridInfoMap?.[normalizedGroupId] as
+      | (GroupInfo & { currentMems?: unknown[]; memVerList?: unknown[] })
+      | undefined;
+    const context: ZaloGroupContext = {
+      groupId: normalizedGroupId,
+      name: normalizeOptionalString(groupInfo?.name),
+      members: extractGroupMembersFromInfo(groupInfo),
+    };
+    writeCachedGroupContext(profile, context);
+    return context;
+  });
 }
 
 export async function sendZaloTextMessage(
@@ -1037,91 +1246,97 @@ export async function sendZaloTextMessage(
     return { ok: false, error: "No threadId provided" };
   }
 
-  const api = await ensureApi(profile);
-  const type = options.isGroup ? ThreadType.Group : ThreadType.User;
+  return await withZaloApi(
+    profile,
+    async (api) => {
+      const type = options.isGroup ? ThreadType.Group : ThreadType.User;
 
-  try {
-    if (options.mediaUrl?.trim()) {
-      const media = await loadOutboundMediaFromUrl(options.mediaUrl.trim(), {
-        mediaLocalRoots: options.mediaLocalRoots,
-      });
-      const fileName = resolveMediaFileName({
-        mediaUrl: options.mediaUrl,
-        fileName: media.fileName,
-        contentType: media.contentType,
-        kind: media.kind,
-      });
-      const payloadText = (text || options.caption || "").slice(0, 2000);
-      const textStyles = clampTextStyles(payloadText, options.textStyles);
-
-      if (media.kind === "audio") {
-        let textMessageId: string | undefined;
-        if (payloadText) {
-          const textResponse = await api.sendMessage(
-            textStyles ? { msg: payloadText, styles: textStyles } : payloadText,
+      try {
+        if (options.mediaUrl?.trim()) {
+          const media = await loadOutboundMediaFromUrl(options.mediaUrl.trim(), {
+            mediaLocalRoots: options.mediaLocalRoots,
+            mediaReadFile: options.mediaReadFile,
+          });
+          const fileName = resolveMediaFileName({
+            mediaUrl: options.mediaUrl,
+            fileName: media.fileName,
+            contentType: media.contentType,
+            kind: media.kind,
+          });
+          const payloadText = (text || options.caption || "").slice(0, 2000);
+          const textStyles = clampTextStyles(payloadText, options.textStyles);
+
+          if (media.kind === "audio") {
+            let textMessageId: string | undefined;
+            if (payloadText) {
+              const textResponse = await api.sendMessage(
+                textStyles ? { msg: payloadText, styles: textStyles } : payloadText,
+                trimmedThreadId,
+                type,
+              );
+              textMessageId = extractSendMessageId(textResponse);
+            }
+
+            const attachmentFileName = fileName.includes(".") ? fileName : `${fileName}.bin`;
+            const uploaded = await api.uploadAttachment(
+              [
+                {
+                  data: media.buffer,
+                  filename: attachmentFileName as `${string}.${string}`,
+                  metadata: {
+                    totalSize: media.buffer.length,
+                  },
+                },
+              ],
+              trimmedThreadId,
+              type,
+            );
+            const voiceAsset = resolveUploadedVoiceAsset(uploaded);
+            if (!voiceAsset) {
+              throw new Error("Failed to resolve uploaded audio URL for voice message");
+            }
+            const voiceUrl = buildZaloVoicePlaybackUrl(voiceAsset);
+            const response = await api.sendVoice({ voiceUrl }, trimmedThreadId, type);
+            return {
+              ok: true,
+              messageId: extractSendMessageId(response) ?? textMessageId,
+            };
+          }
+
+          const response = await api.sendMessage(
+            {
+              msg: payloadText,
+              ...(textStyles ? { styles: textStyles } : {}),
+              attachments: [
+                {
+                  data: media.buffer,
+                  filename: fileName.includes(".") ? fileName : `${fileName}.bin`,
+                  metadata: {
+                    totalSize: media.buffer.length,
+                  },
+                },
+              ],
+            },
             trimmedThreadId,
             type,
           );
-          textMessageId = extractSendMessageId(textResponse);
+          return { ok: true, messageId: extractSendMessageId(response) };
         }
 
-        const attachmentFileName = fileName.includes(".") ? fileName : `${fileName}.bin`;
-        const uploaded = await api.uploadAttachment(
-          [
-            {
-              data: media.buffer,
-              filename: attachmentFileName as `${string}.${string}`,
-              metadata: {
-                totalSize: media.buffer.length,
-              },
-            },
-          ],
+        const payloadText = text.slice(0, 2000);
+        const textStyles = clampTextStyles(payloadText, options.textStyles);
+        const response = await api.sendMessage(
+          textStyles ? { msg: payloadText, styles: textStyles } : payloadText,
           trimmedThreadId,
           type,
         );
-        const voiceAsset = resolveUploadedVoiceAsset(uploaded);
-        if (!voiceAsset) {
-          throw new Error("Failed to resolve uploaded audio URL for voice message");
-        }
-        const voiceUrl = buildZaloVoicePlaybackUrl(voiceAsset);
-        const response = await api.sendVoice({ voiceUrl }, trimmedThreadId, type);
-        return {
-          ok: true,
-          messageId: extractSendMessageId(response) ?? textMessageId,
-        };
+        return { ok: true, messageId: extractSendMessageId(response) };
+      } catch (error) {
+        return { ok: false, error: toErrorMessage(error) };
       }
-
-      const response = await api.sendMessage(
-        {
-          msg: payloadText,
-          ...(textStyles ? { styles: textStyles } : {}),
-          attachments: [
-            {
-              data: media.buffer,
-              filename: fileName.includes(".") ? fileName : `${fileName}.bin`,
-              metadata: {
-                totalSize: media.buffer.length,
-              },
-            },
-          ],
-        },
-        trimmedThreadId,
-        type,
-      );
-      return { ok: true, messageId: extractSendMessageId(response) };
-    }
-
-    const payloadText = text.slice(0, 2000);
-    const textStyles = clampTextStyles(payloadText, options.textStyles);
-    const response = await api.sendMessage(
-      textStyles ? { msg: payloadText, styles: textStyles } : payloadText,
-      trimmedThreadId,
-      type,
-    );
-    return { ok: true, messageId: extractSendMessageId(response) };
-  } catch (error) {
-    return { ok: false, error: toErrorMessage(error) };
-  }
+    },
+    { shouldPersist: (result) => result.ok },
+  );
 }
 
 export async function sendZaloTypingEvent(
@@ -1133,13 +1348,14 @@ export async function sendZaloTypingEvent(
   if (!trimmedThreadId) {
     throw new Error("No threadId provided");
   }
-  const api = await ensureApi(profile);
-  const type = options.isGroup ? ThreadType.Group : ThreadType.User;
-  if ("sendTypingEvent" in api && typeof api.sendTypingEvent === "function") {
-    await (api as API & ApiTypingCapability).sendTypingEvent(trimmedThreadId, type);
-    return;
-  }
-  throw new Error("Zalo typing indicator is not supported by current API session");
+  await withZaloApi(profile, async (api) => {
+    const type = options.isGroup ? ThreadType.Group : ThreadType.User;
+    if ("sendTypingEvent" in api && typeof api.sendTypingEvent === "function") {
+      await (api as API & ApiTypingCapability).sendTypingEvent(trimmedThreadId, type);
+      return;
+    }
+    throw new Error("Zalo typing indicator is not supported by current API session");
+  });
 }
 
 async function resolveOwnUserId(api: API): Promise<string> {
@@ -1182,17 +1398,22 @@ export async function sendZaloReaction(params: {
     return { ok: false, error: "threadId, msgId, and cliMsgId are required" };
   }
   try {
-    const api = await ensureApi(profile);
-    const type = params.isGroup ? ThreadType.Group : ThreadType.User;
-    const icon = params.remove
-      ? { rType: -1, source: 6, icon: "" }
-      : normalizeZaloReactionIcon(params.emoji);
-    await api.addReaction(icon, {
-      data: { msgId, cliMsgId },
-      threadId,
-      type,
-    });
-    return { ok: true };
+    return await withZaloApi(
+      profile,
+      async (api) => {
+        const type = params.isGroup ? ThreadType.Group : ThreadType.User;
+        const icon = params.remove
+          ? { rType: -1, source: 6, icon: "" }
+          : normalizeZaloReactionIcon(params.emoji);
+        await api.addReaction(icon, {
+          data: { msgId, cliMsgId },
+          threadId,
+          type,
+        });
+        return { ok: true };
+      },
+      { shouldPersist: (result) => result.ok },
+    );
   } catch (error) {
     return { ok: false, error: toErrorMessage(error) };
   }
@@ -1205,9 +1426,10 @@ export async function sendZaloDeliveredEvent(params: {
   isSeen?: boolean;
 }): Promise<void> {
   const profile = normalizeProfile(params.profile);
-  const api = await ensureApi(profile);
-  const type = params.isGroup ? ThreadType.Group : ThreadType.User;
-  await api.sendDeliveredEvent(params.isSeen === true, params.message, type);
+  await withZaloApi(profile, async (api) => {
+    const type = params.isGroup ? ThreadType.Group : ThreadType.User;
+    await api.sendDeliveredEvent(params.isSeen === true, params.message, type);
+  });
 }
 
 export async function sendZaloSeenEvent(params: {
@@ -1216,9 +1438,10 @@ export async function sendZaloSeenEvent(params: {
   message: ZaloEventMessage;
 }): Promise<void> {
   const profile = normalizeProfile(params.profile);
-  const api = await ensureApi(profile);
-  const type = params.isGroup ? ThreadType.Group : ThreadType.User;
-  await api.sendSeenEvent(params.message, type);
+  await withZaloApi(profile, async (api) => {
+    const type = params.isGroup ? ThreadType.Group : ThreadType.User;
+    await api.sendSeenEvent(params.message, type);
+  });
 }
 
 export async function sendZaloLink(
@@ -1237,14 +1460,19 @@ export async function sendZaloLink(
   }
 
   try {
-    const api = await ensureApi(profile);
-    const type = options.isGroup ? ThreadType.Group : ThreadType.User;
-    const response = await api.sendLink(
-      { link: trimmedUrl, msg: options.caption },
-      trimmedThreadId,
-      type,
+    return await withZaloApi(
+      profile,
+      async (api) => {
+        const type = options.isGroup ? ThreadType.Group : ThreadType.User;
+        const response = await api.sendLink(
+          { link: trimmedUrl, msg: options.caption },
+          trimmedThreadId,
+          type,
+        );
+        return { ok: true, messageId: String(response.msgId) };
+      },
+      { shouldPersist: (result) => result.ok },
     );
-    return { ok: true, messageId: String(response.msgId) };
   } catch (error) {
     return { ok: false, error: toErrorMessage(error) };
   }
@@ -1294,7 +1522,7 @@ export async function startZaloQrLogin(params: {
       let capturedCredentials: Omit<StoredZaloCredentials, "createdAt" | "lastUsedAt"> | null =
         null;
       try {
-        const zalo = new Zalo({ logging: false, selfListen: false });
+        const zalo = await createZalo({ logging: false, selfListen: false });
         const api = await zalo.loginQR(undefined, (event: LoginQRCallbackEvent) => {
           const current = activeQrLogins.get(profile);
           if (!current || current.id !== login.id) {
@@ -1361,7 +1589,7 @@ export async function startZaloQrLogin(params: {
           };
         }
 
-        writeCredentials(profile, capturedCredentials);
+        writeApiCredentials(profile, api, capturedCredentials ?? undefined);
         invalidateApi(profile);
         apiByProfile.set(profile, api);
         current.connected = true;
@@ -1503,12 +1731,14 @@ export async function startZaloListener(params: {
   const existing = activeListeners.get(profile);
   if (existing) {
     throw new Error(
-      `Zalo listener already running for profile \"${profile}\" (account \"${existing.accountId}\")`,
+      `Zalo listener already running for profile "${profile}" (account "${existing.accountId}")`,
     );
   }
 
-  const api = await ensureApi(profile);
-  const ownUserId = await resolveOwnUserId(api);
+  const { api, ownUserId } = await withZaloApi(profile, async (api) => ({
+    api,
+    ownUserId: await resolveOwnUserId(api),
+  }));
   let stopped = false;
   let watchdogTimer: ReturnType<typeof setInterval> | null = null;
   let lastWatchdogTickAt = Date.now();
@@ -1619,7 +1849,7 @@ export async function resolveZaloGroupsByEntries(params: {
   const groups = await listZaloGroups(params.profile);
   const byName = new Map<string, ZaloGroup[]>();
   for (const group of groups) {
-    const key = group.name.trim().toLowerCase();
+    const key = normalizeOptionalLowercaseString(group.name);
     if (!key) {
       continue;
     }
@@ -1636,7 +1866,7 @@ export async function resolveZaloGroupsByEntries(params: {
     if (/^\d+$/.test(trimmed)) {
       return { input, resolved: true, id: trimmed };
     }
-    const candidates = byName.get(trimmed.toLowerCase()) ?? [];
+    const candidates = byName.get(normalizeLowercaseStringOrEmpty(trimmed)) ?? [];
     const match = candidates[0];
     return match ? { input, resolved: true, id: match.groupId } : { input, resolved: false };
   });
@@ -1649,7 +1879,7 @@ export async function resolveZaloAllowFromEntries(params: {
   const friends = await listZaloFriends(params.profile);
   const byName = new Map<string, ZcaFriend[]>();
   for (const friend of friends) {
-    const key = friend.displayName.trim().toLowerCase();
+    const key = normalizeOptionalLowercaseString(friend.displayName);
     if (!key) {
       continue;
     }
@@ -1666,7 +1896,7 @@ export async function resolveZaloAllowFromEntries(params: {
     if (/^\d+$/.test(trimmed)) {
       return { input, resolved: true, id: trimmed };
     }
-    const matches = byName.get(trimmed.toLowerCase()) ?? [];
+    const matches = byName.get(normalizeLowercaseStringOrEmpty(trimmed)) ?? [];
     const match = matches[0];
     if (!match) {
       return { input, resolved: false };
@@ -1679,16 +1909,3 @@ export async function resolveZaloAllowFromEntries(params: {
     };
   });
 }
-
-export async function clearProfileRuntimeArtifacts(profileInput?: string | null): Promise<void> {
-  const profile = normalizeProfile(profileInput);
-  resetQrLogin(profile);
-  clearCachedGroupContext(profile);
-  const listener = activeListeners.get(profile);
-  if (listener) {
-    listener.stop();
-    activeListeners.delete(profile);
-  }
-  invalidateApi(profile);
-  await fsp.mkdir(resolveCredentialsDir(), { recursive: true }).catch(() => undefined);
-}