nfx-ui 0.20.0 → 0.22.0

package/src/apis/repositories/AuthRepository.ts

@@ -0,0 +1,344 @@
+import type { DataResponse, FullAccountInfoByKind, ListDTOWithTotalNumber, Login, Profile, ProfileItemsByKind, Signup, Tokens } from "@/types";
+
+import { ProfileKindEnum } from "@/enums";
+
+import { protectedClient, publicClient, publicClientWithoutTransform } from "../clients";
+import { dataFromResponse, URL_PATHS } from "../ip";
+
+export interface AuthRepository {
+  GetErrorTranslations(lang: string): Promise<Record<string, string>>;
+  SendVerificationCode(params: Signup.Request.SendVerificationCode): Promise<void>;
+  SignupWithEmail(params: Signup.Request.SignupWithEmail): Promise<Signup.Response.SignupWithEmail>;
+  LoginWithEmail(params: Login.Request.LoginWithEmail): Promise<Login.Response.LoginWithEmail>;
+  LoginWithPhone(params: Login.Request.LoginWithPhone): Promise<Login.Response.LoginWithPhone>;
+  GetGitHubAuthorizeUrl(): Promise<Login.Response.GitHubAuthorizeUrl>;
+  LoginWithGitHub(params: Login.Request.LoginWithGitHub): Promise<Login.Response.LoginWithGitHub>;
+  LinkGitHub(params: Login.Request.LinkGitHub): Promise<void>;
+  UnlinkGitHub(): Promise<void>;
+  SelectProfile(params: Login.Request.SelectProfile): Promise<Login.Response.SelectProfile>;
+  GetCurrentFullAccountInformationWithProfile<K extends ProfileKindEnum>(kind: K): Promise<FullAccountInfoByKind<K>>;
+  PatchProfile(kind: ProfileKindEnum, body: Profile.Request.PatchProfile): Promise<void>;
+  PatchProfileSettings(kind: ProfileKindEnum, body: Profile.Request.PatchProfileSettings): Promise<void>;
+  ConfirmProfileAvatar(kind: ProfileKindEnum, body: Profile.Request.ConfirmProfileAvatar): Promise<void>;
+  ClearProfileAvatar(kind: ProfileKindEnum): Promise<void>;
+  ConfirmProfileBackgrounds(kind: ProfileKindEnum, body: Profile.Request.ConfirmProfileBackgrounds): Promise<void>;
+  ListProfiles<K extends ProfileKindEnum>(kind: K, params?: { limit?: number; offset?: number }): Promise<ListDTOWithTotalNumber<ProfileItemsByKind<K>[number]>>;
+  DeleteProfile(kind: ProfileKindEnum, profileId: string): Promise<void>;
+  UpdatePreference(kind: ProfileKindEnum, preference: string): Promise<void>;
+  CreateForgerProfile(body: Login.Request.CreateForgerProfile): Promise<Login.Response.CreateForgerProfile>;
+  CreateAuthorityProfile(body: Login.Request.CreateAuthorityProfile): Promise<Login.Response.CreateAuthorityProfile>;
+  SearchForgerProfiles(params: Profile.Request.SearchProfiles): Promise<ListDTOWithTotalNumber<Profile.Response.ForgerProfileItem>>;
+  SearchAuthorityProfiles(params: Profile.Request.SearchProfiles): Promise<ListDTOWithTotalNumber<Profile.Response.AuthorityProfileItem>>;
+  GetPublicProfileCard(profileId: string): Promise<Profile.Response.ForgerProfileItem>;
+  ListEmails(params?: { limit?: number; offset?: number }): Promise<ListDTOWithTotalNumber<Login.EmailItem>>;
+  CreateEmail(body: Login.Request.CreateEmail): Promise<Login.Response.CreateEmail>;
+  SendEmailVerificationCode(emailId: string, body?: Login.Request.SendEmailVerificationCode): Promise<void>;
+  VerifyEmail(emailId: string, body: Login.Request.VerifyEmail): Promise<void>;
+  UpdateEmail(emailId: string, body: Login.Request.UpdateEmail): Promise<void>;
+  SetPrimaryEmail(emailId: string): Promise<void>;
+  DeleteEmail(emailId: string): Promise<void>;
+  ListPhones(params?: { limit?: number; offset?: number }): Promise<ListDTOWithTotalNumber<Login.PhoneItem>>;
+  CreatePhone(body: Login.Request.CreatePhone): Promise<Login.Response.CreatePhone>;
+  SendPhoneVerificationCode(phoneId: string): Promise<void>;
+  VerifyPhone(phoneId: string, body: Login.Request.VerifyPhone): Promise<void>;
+  UpdatePhone(phoneId: string, body: Login.Request.UpdatePhone): Promise<void>;
+  SetPrimaryPhone(phoneId: string): Promise<void>;
+  DeletePhone(phoneId: string): Promise<void>;
+  SendChangePasswordVerificationCode(body?: Login.Request.SendChangePasswordVerificationCode): Promise<void>;
+  ChangePassword(body: Login.Request.ChangePassword): Promise<void>;
+  RefreshTokens(params: Tokens.Request.RefreshTokens): Promise<Tokens.Response.Tokens>;
+  Logout(params: Tokens.Request.Logout): Promise<void>;
+  ListOwnerForgerProfiles(params?: { limit?: number; offset?: number; query?: string }): Promise<ListDTOWithTotalNumber<Profile.Response.ForgerProfileItem>>;
+  ListOwnerAuthorityProfiles(params?: { limit?: number; offset?: number; query?: string }): Promise<ListDTOWithTotalNumber<Profile.Response.AuthorityProfileItem>>;
+  UpdateAuthorityProfileRoles(profileId: string, params: Profile.Request.UpdateAuthorityProfileRoles): Promise<void>;
+}
+
+export class ApiAuthRepository implements AuthRepository {
+  async GetErrorTranslations(lang: string): Promise<Record<string, string>> {
+    const { data } = await publicClientWithoutTransform.get<Record<string, string>>(URL_PATHS.AUTH.Locales.errorsByLang(lang));
+    return data;
+  }
+
+  async SendVerificationCode(params: Signup.Request.SendVerificationCode): Promise<void> {
+    await publicClient.post(URL_PATHS.AUTH.SignupSendCode, params);
+  }
+
+  async SignupWithEmail(params: Signup.Request.SignupWithEmail): Promise<Signup.Response.SignupWithEmail> {
+    const { data } = await publicClient.post<DataResponse<Signup.Response.SignupWithEmail>>(URL_PATHS.AUTH.SignupWithEmail, params);
+    return data.data;
+  }
+
+  async LoginWithEmail(params: Login.Request.LoginWithEmail): Promise<Login.Response.LoginWithEmail> {
+    const { data } = await publicClient.post<DataResponse<Login.Response.LoginWithEmail>>(URL_PATHS.AUTH.LoginWithEmail, params);
+    return data.data;
+  }
+
+  async LoginWithPhone(params: Login.Request.LoginWithPhone): Promise<Login.Response.LoginWithPhone> {
+    const { data } = await publicClient.post<DataResponse<Login.Response.LoginWithPhone>>(URL_PATHS.AUTH.LoginWithPhone, params);
+    return data.data;
+  }
+
+  async GetGitHubAuthorizeUrl(): Promise<Login.Response.GitHubAuthorizeUrl> {
+    const { data } = await publicClient.get<DataResponse<Login.Response.GitHubAuthorizeUrl>>(URL_PATHS.AUTH.LoginGitHubUrl);
+    return data.data;
+  }
+
+  async LoginWithGitHub(params: Login.Request.LoginWithGitHub): Promise<Login.Response.LoginWithGitHub> {
+    const { data } = await publicClient.post<DataResponse<Login.Response.LoginWithGitHub>>(URL_PATHS.AUTH.LoginGitHub, params);
+    return data.data;
+  }
+
+  async LinkGitHub(params: Login.Request.LinkGitHub): Promise<void> {
+    await protectedClient.post(URL_PATHS.AUTH.Me.GitHub, params);
+  }
+
+  async UnlinkGitHub(): Promise<void> {
+    await protectedClient.delete(URL_PATHS.AUTH.Me.GitHub);
+  }
+
+  async SelectProfile(params: Login.Request.SelectProfile): Promise<Login.Response.SelectProfile> {
+    const { data } = await protectedClient.post<DataResponse<Login.Response.SelectProfile>>(URL_PATHS.AUTH.Me.SelectProfile, params);
+    return dataFromResponse(data, "SelectProfile");
+  }
+
+  async GetCurrentFullAccountInformationWithProfile<K extends ProfileKindEnum>(kind: K): Promise<FullAccountInfoByKind<K>> {
+    switch (kind) {
+      case ProfileKindEnum.FORGER: {
+        const { data } = await protectedClient.get<DataResponse<Profile.Response.FullAccountInformationWithForgerProfile>>(
+          URL_PATHS.AUTH.Me.FullAccountInformationWithForgerProfile,
+        );
+        return dataFromResponse(data, "GetCurrentFullAccountInformationWithProfile") as FullAccountInfoByKind<K>;
+      }
+      case ProfileKindEnum.AUTHORITY: {
+        const { data } = await protectedClient.get<DataResponse<Profile.Response.FullAccountInformationWithAuthorityProfile>>(
+          URL_PATHS.AUTH.Me.FullAccountInformationWithAuthorityProfile,
+        );
+        return dataFromResponse(data, "GetCurrentFullAccountInformationWithProfile") as FullAccountInfoByKind<K>;
+      }
+      default:
+        throw new Error("Invalid profile kind");
+    }
+  }
+
+  async PatchProfile(kind: ProfileKindEnum, body: Profile.Request.PatchProfile): Promise<void> {
+    switch (kind) {
+      case ProfileKindEnum.FORGER:
+        await protectedClient.patch<DataResponse<null>>(URL_PATHS.AUTH.Me.ForgerProfile, body);
+        return;
+      case ProfileKindEnum.AUTHORITY:
+        await protectedClient.patch<DataResponse<null>>(URL_PATHS.AUTH.Me.AuthorityProfile, body);
+        return;
+      default:
+        throw new Error("Invalid profile kind");
+    }
+  }
+
+  async PatchProfileSettings(kind: ProfileKindEnum, body: Profile.Request.PatchProfileSettings): Promise<void> {
+    switch (kind) {
+      case ProfileKindEnum.FORGER:
+        await protectedClient.patch<DataResponse<null>>(URL_PATHS.AUTH.Me.ForgerProfileSettings, body);
+        return;
+      case ProfileKindEnum.AUTHORITY:
+        await protectedClient.patch<DataResponse<null>>(URL_PATHS.AUTH.Me.AuthorityProfileSettings, body);
+        return;
+      default:
+        throw new Error("Invalid profile kind");
+    }
+  }
+
+  async ConfirmProfileAvatar(kind: ProfileKindEnum, body: Profile.Request.ConfirmProfileAvatar): Promise<void> {
+    switch (kind) {
+      case ProfileKindEnum.FORGER:
+        await protectedClient.put<DataResponse<null>>(URL_PATHS.AUTH.Me.ForgerProfileAvatars, body);
+        return;
+      case ProfileKindEnum.AUTHORITY:
+        await protectedClient.put<DataResponse<null>>(URL_PATHS.AUTH.Me.AuthorityProfileAvatars, body);
+        return;
+      default:
+        throw new Error("Invalid profile kind");
+    }
+  }
+
+  async ClearProfileAvatar(kind: ProfileKindEnum): Promise<void> {
+    switch (kind) {
+      case ProfileKindEnum.FORGER:
+        await protectedClient.delete<DataResponse<null>>(URL_PATHS.AUTH.Me.ForgerProfileAvatars);
+        return;
+      case ProfileKindEnum.AUTHORITY:
+        await protectedClient.delete<DataResponse<null>>(URL_PATHS.AUTH.Me.AuthorityProfileAvatars);
+        return;
+      default:
+        throw new Error("Invalid profile kind");
+    }
+  }
+
+  async ConfirmProfileBackgrounds(kind: ProfileKindEnum, body: Profile.Request.ConfirmProfileBackgrounds): Promise<void> {
+    switch (kind) {
+      case ProfileKindEnum.FORGER:
+        await protectedClient.put<DataResponse<null>>(URL_PATHS.AUTH.Me.ForgerProfileBackgrounds, body);
+        return;
+      case ProfileKindEnum.AUTHORITY:
+        await protectedClient.put<DataResponse<null>>(URL_PATHS.AUTH.Me.AuthorityProfileBackgrounds, body);
+        return;
+      default:
+        throw new Error("Invalid profile kind");
+    }
+  }
+
+  async ListProfiles<K extends ProfileKindEnum>(kind: K, params: { limit?: number; offset?: number } = {}): Promise<ListDTOWithTotalNumber<ProfileItemsByKind<K>[number]>> {
+    switch (kind) {
+      case ProfileKindEnum.FORGER: {
+        const { data } = await protectedClient.get<DataResponse<ListDTOWithTotalNumber<Profile.Response.ForgerProfileItem>>>(URL_PATHS.AUTH.Me.Profiles, { params });
+        return dataFromResponse(data, "ListProfiles") as ListDTOWithTotalNumber<ProfileItemsByKind<K>[number]>;
+      }
+      case ProfileKindEnum.AUTHORITY: {
+        const { data } = await protectedClient.get<DataResponse<ListDTOWithTotalNumber<Profile.Response.AuthorityProfileItem>>>(URL_PATHS.AUTH.Me.AuthorityProfiles, { params });
+        return dataFromResponse(data, "ListProfiles") as ListDTOWithTotalNumber<ProfileItemsByKind<K>[number]>;
+      }
+      default:
+        throw new Error("Invalid profile kind");
+    }
+  }
+
+  async DeleteProfile(kind: ProfileKindEnum, profileId: string): Promise<void> {
+    switch (kind) {
+      case ProfileKindEnum.FORGER:
+        await protectedClient.delete<DataResponse<null>>(URL_PATHS.AUTH.Me.ProfileById(profileId));
+        return;
+      case ProfileKindEnum.AUTHORITY:
+        await protectedClient.delete<DataResponse<null>>(URL_PATHS.AUTH.Me.AuthorityProfileById(profileId));
+        return;
+      default:
+        throw new Error("Invalid profile kind");
+    }
+  }
+
+  async UpdatePreference(kind: ProfileKindEnum, preference: string): Promise<void> {
+    switch (kind) {
+      case ProfileKindEnum.FORGER:
+        await protectedClient.put<DataResponse<null>>(URL_PATHS.AUTH.Me.ForgerProfilePreference, { preference });
+        return;
+      case ProfileKindEnum.AUTHORITY:
+        await protectedClient.put<DataResponse<null>>(URL_PATHS.AUTH.Me.AuthorityProfilePreference, { preference });
+        return;
+      default:
+        throw new Error("Invalid profile kind");
+    }
+  }
+
+  async CreateForgerProfile(body: Login.Request.CreateForgerProfile): Promise<Login.Response.CreateForgerProfile> {
+    const { data } = await protectedClient.post<DataResponse<Login.Response.CreateForgerProfile>>(URL_PATHS.AUTH.Me.Profiles, body);
+    return dataFromResponse(data, "CreateForgerProfile");
+  }
+
+  async CreateAuthorityProfile(body: Login.Request.CreateAuthorityProfile): Promise<Login.Response.CreateAuthorityProfile> {
+    const { data } = await protectedClient.post<DataResponse<Login.Response.CreateAuthorityProfile>>(URL_PATHS.AUTH.Me.AuthorityProfiles, body);
+    return dataFromResponse(data, "CreateAuthorityProfile");
+  }
+
+  async SearchForgerProfiles(params: Profile.Request.SearchProfiles): Promise<ListDTOWithTotalNumber<Profile.Response.ForgerProfileItem>> {
+    const { data } = await protectedClient.post<DataResponse<ListDTOWithTotalNumber<Profile.Response.ForgerProfileItem>>>(URL_PATHS.AUTH.Me.SearchForgerProfiles, params);
+    return dataFromResponse(data, "SearchForgerProfiles");
+  }
+
+  async SearchAuthorityProfiles(params: Profile.Request.SearchProfiles): Promise<ListDTOWithTotalNumber<Profile.Response.AuthorityProfileItem>> {
+    const { data } = await protectedClient.post<DataResponse<ListDTOWithTotalNumber<Profile.Response.AuthorityProfileItem>>>(URL_PATHS.AUTH.Me.SearchAuthorityProfiles, params);
+    return dataFromResponse(data, "SearchAuthorityProfiles");
+  }
+
+  async GetPublicProfileCard(profileId: string): Promise<Profile.Response.ForgerProfileItem> {
+    const { data } = await protectedClient.get<DataResponse<Profile.Response.ForgerProfileItem>>(URL_PATHS.AUTH.Me.PublicProfileCardById(profileId));
+    return dataFromResponse(data, "GetPublicProfileCard");
+  }
+
+  async ListEmails(params: { limit?: number; offset?: number } = {}): Promise<ListDTOWithTotalNumber<Login.EmailItem>> {
+    const { data } = await protectedClient.get<DataResponse<ListDTOWithTotalNumber<Login.EmailItem>>>(URL_PATHS.AUTH.Me.Emails, { params });
+    return dataFromResponse(data, "ListEmails");
+  }
+
+  async CreateEmail(body: Login.Request.CreateEmail): Promise<Login.Response.CreateEmail> {
+    const { data } = await protectedClient.post<DataResponse<Login.Response.CreateEmail>>(URL_PATHS.AUTH.Me.Emails, body);
+    return dataFromResponse(data, "CreateEmail");
+  }
+
+  async SendEmailVerificationCode(emailId: string, body: Login.Request.SendEmailVerificationCode = {}): Promise<void> {
+    await protectedClient.post(URL_PATHS.AUTH.Me.EmailSendVerificationCode(emailId), body);
+  }
+
+  async VerifyEmail(emailId: string, body: Login.Request.VerifyEmail): Promise<void> {
+    await protectedClient.post(URL_PATHS.AUTH.Me.EmailVerify(emailId), body);
+  }
+
+  async UpdateEmail(emailId: string, body: Login.Request.UpdateEmail): Promise<void> {
+    await protectedClient.patch(URL_PATHS.AUTH.Me.EmailById(emailId), body);
+  }
+
+  async SetPrimaryEmail(emailId: string): Promise<void> {
+    await protectedClient.put(URL_PATHS.AUTH.Me.EmailPrimary(emailId));
+  }
+
+  async DeleteEmail(emailId: string): Promise<void> {
+    await protectedClient.delete(URL_PATHS.AUTH.Me.EmailById(emailId));
+  }
+
+  async ListPhones(params: { limit?: number; offset?: number } = {}): Promise<ListDTOWithTotalNumber<Login.PhoneItem>> {
+    const { data } = await protectedClient.get<DataResponse<ListDTOWithTotalNumber<Login.PhoneItem>>>(URL_PATHS.AUTH.Me.Phones, { params });
+    return dataFromResponse(data, "ListPhones");
+  }
+
+  async CreatePhone(body: Login.Request.CreatePhone): Promise<Login.Response.CreatePhone> {
+    const { data } = await protectedClient.post<DataResponse<Login.Response.CreatePhone>>(URL_PATHS.AUTH.Me.Phones, body);
+    return dataFromResponse(data, "CreatePhone");
+  }
+
+  async SendPhoneVerificationCode(phoneId: string): Promise<void> {
+    await protectedClient.post(URL_PATHS.AUTH.Me.PhoneSendVerificationCode(phoneId));
+  }
+
+  async VerifyPhone(phoneId: string, body: Login.Request.VerifyPhone): Promise<void> {
+    await protectedClient.post(URL_PATHS.AUTH.Me.PhoneVerify(phoneId), body);
+  }
+
+  async UpdatePhone(phoneId: string, body: Login.Request.UpdatePhone): Promise<void> {
+    await protectedClient.patch(URL_PATHS.AUTH.Me.PhoneById(phoneId), body);
+  }
+
+  async SetPrimaryPhone(phoneId: string): Promise<void> {
+    await protectedClient.put(URL_PATHS.AUTH.Me.PhonePrimary(phoneId));
+  }
+
+  async DeletePhone(phoneId: string): Promise<void> {
+    await protectedClient.delete(URL_PATHS.AUTH.Me.PhoneById(phoneId));
+  }
+
+  async SendChangePasswordVerificationCode(body: Login.Request.SendChangePasswordVerificationCode = {}): Promise<void> {
+    await protectedClient.post(URL_PATHS.AUTH.Me.PasswordSendVerificationCode, body);
+  }
+
+  async ChangePassword(body: Login.Request.ChangePassword): Promise<void> {
+    await protectedClient.put(URL_PATHS.AUTH.Me.Password, body);
+  }
+
+  async RefreshTokens(params: Tokens.Request.RefreshTokens): Promise<Tokens.Response.Tokens> {
+    const { data } = await publicClient.post<DataResponse<Tokens.Response.Tokens>>(URL_PATHS.AUTH.Refresh, params);
+    return dataFromResponse(data, "RefreshTokens");
+  }
+
+  async Logout(params: Tokens.Request.Logout): Promise<void> {
+    await publicClient.post(URL_PATHS.AUTH.Logout, params);
+  }
+
+  async ListOwnerForgerProfiles(params: { limit?: number; offset?: number; query?: string } = {}): Promise<ListDTOWithTotalNumber<Profile.Response.ForgerProfileItem>> {
+    const { data } = await protectedClient.get<DataResponse<ListDTOWithTotalNumber<Profile.Response.ForgerProfileItem>>>(URL_PATHS.AUTH.Owner.ForgerProfiles, { params });
+    return dataFromResponse(data, "ListOwnerForgerProfiles");
+  }
+
+  async ListOwnerAuthorityProfiles(params: { limit?: number; offset?: number; query?: string } = {}): Promise<ListDTOWithTotalNumber<Profile.Response.AuthorityProfileItem>> {
+    const { data } = await protectedClient.get<DataResponse<ListDTOWithTotalNumber<Profile.Response.AuthorityProfileItem>>>(URL_PATHS.AUTH.Owner.AuthorityProfiles, { params });
+    return dataFromResponse(data, "ListOwnerAuthorityProfiles");
+  }
+
+  async UpdateAuthorityProfileRoles(profileId: string, params: Profile.Request.UpdateAuthorityProfileRoles): Promise<void> {
+    await protectedClient.patch(URL_PATHS.AUTH.Owner.UpdateAuthorityProfileRoles(profileId), params);
+  }
+}

package/src/apis/repositories/context.tsx

@@ -0,0 +1,27 @@
+import type { AssetRepository } from "./AssetRepository";
+import type { AuthRepository } from "./AuthRepository";
+
+import { createContext, useContext } from "react";
+
+export interface IdentityRepositories {
+  auth: AuthRepository;
+  asset: AssetRepository;
+}
+
+export const IdentityRepositoriesContext = createContext<Nullable<IdentityRepositories>>(null);
+
+export function useIdentityRepositories(): IdentityRepositories {
+  const ctx = useContext(IdentityRepositoriesContext);
+  if (!ctx) {
+    throw new Error("useIdentityRepositories must be used inside NFX-UI DataProvider");
+  }
+  return ctx;
+}
+
+export function useAuthRepository() {
+  return useIdentityRepositories().auth;
+}
+
+export function useAssetRepository() {
+  return useIdentityRepositories().asset;
+}

package/src/apis/repositories/index.ts

@@ -0,0 +1,11 @@
+export type { AuthRepository } from "./AuthRepository";
+export { ApiAuthRepository } from "./AuthRepository";
+export type { AssetRepository } from "./AssetRepository";
+export { ApiAssetRepository } from "./AssetRepository";
+export {
+  type IdentityRepositories,
+  IdentityRepositoriesContext,
+  useIdentityRepositories,
+  useAuthRepository,
+  useAssetRepository,
+} from "./context";

package/src/config/env.ts

@@ -0,0 +1,22 @@
+import { safeOr, safeStringable } from "@/utils/safe";
+
+function resolveApiUrl(): string {
+  const raw = safeStringable(import.meta.env.VITE_API_URL).trim();
+  if (raw === "") {
+    if (import.meta.env.DEV) {
+      throw new Error("[env] 请在 .env（secure 时 .secure.env）中设置 VITE_API_URL（主 API 根地址）。");
+    }
+    return "";
+  }
+  return raw.replace(/\/$/, "");
+}
+
+export const appEnv = {
+  buildEnv: import.meta.env.VITE_BUILD_ENV,
+  appId: import.meta.env.VITE_APP_ID,
+  name: safeOr(import.meta.env.VITE_NAME, "NFX"),
+  apiUrl: resolveApiUrl(),
+  devApiProxyTarget: import.meta.env.VITE_DEV_API_PROXY_TARGET,
+} as const;
+
+export const APP_NAME = appEnv.name;

package/src/config/global.d.ts

@@ -0,0 +1,32 @@
+import type {
+  Array as _Array,
+  Defined as _Defined,
+  Emptyable as _Emptyable,
+  ExistenceResult as _ExistenceResult,
+  KeyOf as _KeyOf,
+  Maybe as _Maybe,
+  Nilable as _Nilable,
+  Nullable as _Nullable,
+  Objectable as _Objectable,
+  Stringable as _Stringable,
+  ValueOf as _ValueOf,
+  Zeroable as _Zeroable,
+  isOK as _IsOK,
+} from "./types/utils";
+
+export {};
+
+declare global {
+  type Nullable<T> = _Nullable<T>;
+  type Maybe<T> = _Maybe<T>;
+  type Nilable<T> = _Nilable<T>;
+  type Emptyable<T> = _Emptyable<T>;
+  type Zeroable<T extends number> = _Zeroable<T>;
+  type Stringable<T extends string> = _Stringable<T>;
+  type Objectable<T extends Record<string, unknown>> = _Objectable<T>;
+  type ExistenceResult<T> = _ExistenceResult<T>;
+  type ValueOf<T> = _ValueOf<T>;
+  type KeyOf<T> = _KeyOf<T>;
+  type Defined<T, Tag extends string> = _Defined<T, Tag>;
+  type isOK<T> = _IsOK<T>;
+}

package/src/config/index.ts

@@ -0,0 +1,2 @@
+export * from "./env";
+export type * from "./type-utils";

package/src/config/type-utils.ts

@@ -0,0 +1,18 @@
+/**
+ * Shared utility types (source of truth in config layer).
+ */
+export type Nullable<T> = T | null;
+export type Maybe<T> = T | undefined;
+export type Nilable<T> = T | null | undefined;
+export type Emptyable<T> = T | null | undefined | "";
+export type Zeroable<T extends number> = T | 0;
+export type Stringable<T extends string> = T | "";
+export type Objectable<T extends Record<string, unknown>> = T | {};
+export type Arrayable<T> = Array<T> | T[];
+export type ExistenceResult<T> = [T, true] | [null, false];
+export type ValueOf<T> = T[keyof T];
+export type KeyOf<T> = keyof T;
+export type Defined<T, Tag extends string> = T & {
+  readonly __defineBrand?: Tag;
+};
+export type IsOK<T> = [T, true] | [null, false];

package/src/constants/caches.ts

@@ -0,0 +1,7 @@
+/** 列表 key 片段。List key segment. */
+const CACHE_LIST = "list";
+
+/** 单条 key 片段。Item key segment. */
+const CACHE_ITEM = "item";
+
+export { CACHE_LIST, CACHE_ITEM };

package/src/constants/enums.ts

@@ -0,0 +1,32 @@
+type EnumMetaMap = Record<string, Record<PropertyKey, unknown>>;
+
+type DefinedEnum<M extends EnumMetaMap> = {
+  Values: readonly (keyof M)[];
+  pickMap<P extends keyof M[keyof M]>(prop: P): { [K in keyof M]: M[K][P] };
+  get<K extends keyof M>(key: K): M[K];
+};
+
+type EnumInferMeta<E> = E extends DefinedEnum<infer M> ? M : never;
+
+type EnumValue<E extends { Values: readonly PropertyKey[] }> = E["Values"][number];
+
+function defineEnum<const M extends EnumMetaMap>(metaMap: M): DefinedEnum<M> {
+  type Key = keyof M;
+  const Values = Object.keys(metaMap) as Key[];
+  function pickMap<P extends keyof M[Key]>(prop: P) {
+    return Object.fromEntries(Object.entries(metaMap).map(([k, v]) => [k, v[prop]])) as {
+      [K in Key]: M[K][P];
+    };
+  }
+  function get<K extends Key>(key: K): M[K] {
+    return metaMap[key];
+  }
+  return { Values, pickMap, get };
+}
+
+function enumPickMap<M extends EnumMetaMap, P extends keyof M[keyof M]>(e: DefinedEnum<M>, prop: P): { [K in keyof M]: M[K][P] } {
+  return e.pickMap(prop) as { [K in keyof M]: M[K][P] };
+}
+
+export { defineEnum, enumPickMap };
+export type { EnumMetaMap, DefinedEnum, EnumInferMeta, EnumValue };

package/src/constants/index.ts

@@ -0,0 +1,10 @@
+/**
+ * 公用常量：query key 工厂、domain 片段、cache 片段、catalog 限制等
+ * Shared constants: query key factories, domain segments, cache segments, catalog limits.
+ */
+export * from "./caches";
+export * from "./enums";
+export * from "./key";
+export * from "./query.itemkeys";
+export * from "./query.listkeys";
+export * from "./querykeys";

package/src/constants/key.ts

@@ -0,0 +1,15 @@
+import type { QueryKey } from "@tanstack/react-query";
+
+import { ProfileKindEnum } from "@/enums";
+
+const DOMAIN_AUTH = "auth";
+
+export const ACCOUNT_SCOPE = (aID: string): QueryKey => [aID];
+export const PROFILE_SCOPE = (aID: string, pID: string): QueryKey => [aID, pID];
+export const AUTH_ACCOUNT_SCOPE = (aID: string): QueryKey => [aID, DOMAIN_AUTH];
+export const AUTH_PROFILE_SCOPE = (aID: string, pID: string): QueryKey => [aID, pID, DOMAIN_AUTH];
+
+export const AUTH_ME = (aID: string, pID: string): QueryKey => [aID, pID, DOMAIN_AUTH, "item", "me"];
+export const AUTH_PROFILES = (aID: string, kind: ProfileKindEnum): QueryKey => [aID, DOMAIN_AUTH, kind, "list", "profiles"];
+export const AUTH_EMAILS = (aID: string): QueryKey => [aID, DOMAIN_AUTH, "list", "emails"];
+export const AUTH_PHONES = (aID: string): QueryKey => [aID, DOMAIN_AUTH, "list", "phones"];

package/src/constants/query.itemkeys.ts

@@ -0,0 +1,66 @@
+/**
+ * 单条 query key 工厂（支持一个或多个 id，可链式 .withPrefix）
+ * Item query key factories (one or more ids, chainable .withPrefix).
+ */
+import type { QueryKey } from "@tanstack/react-query";
+
+import { CACHE_ITEM } from "./caches";
+
+/**
+ * 链式单条 key 类型：可调用 (...ids) => QueryKey，且带 withPrefix、getPrefix。
+ * Chainable item key type: callable (...ids) => QueryKey, with withPrefix() and getPrefix.
+ */
+type ItemKeyChainable = ((...ids: string[]) => QueryKey) & {
+  withPrefix(...prefix: unknown[]): ItemKeyChainable;
+  /** 不含 id 的前缀，用于 invalidation 等。Prefix without ids, e.g. for invalidation. */
+  getPrefix: QueryKey;
+};
+
+function buildItemKeyChainable(prefix: unknown[], domain: string, subDomain: string): ItemKeyChainable {
+  const base: QueryKey = [...prefix, domain, CACHE_ITEM, subDomain];
+  const fn = ((...ids: string[]): QueryKey => [...base, ...ids]) as ItemKeyChainable;
+
+  Object.defineProperty(fn, "withPrefix", {
+    value(...more: unknown[]): ItemKeyChainable {
+      return buildItemKeyChainable([...more, ...prefix], domain, subDomain);
+    },
+    enumerable: false,
+    writable: true,
+    configurable: true,
+  });
+
+  Object.defineProperty(fn, "getPrefix", {
+    get(): QueryKey {
+      return [...base];
+    },
+    enumerable: false,
+    configurable: true,
+  });
+
+  return fn;
+}
+
+/**
+ * 创建「单条」query key 工厂（可链式 .withPrefix）：支持传入一个或多个 id，返回 [domain, CACHE_ITEM, subDomain, ...ids]
+ * Creates an item query key factory (chainable .withPrefix): accepts one or more ids, returns [domain, CACHE_ITEM, subDomain, ...ids].
+ *
+ * @param domain - 域名。Domain name (e.g. "catalog", "auth").
+ * @param subDomain - 子域。Sub-domain (e.g. "category", "product").
+ * @returns 可调用的 key 工厂，带 withPrefix 可链式加前缀。Callable key factory with withPrefix for chaining.
+ * @example
+ * ```ts
+ * const getKey = createItemKey("catalog", "category");
+ * getKey("abc");
+ * * => ["catalog", "item", "category", "abc"]
+ * getKey.getPrefix
+ * * => ["catalog", "item", "category"]
+ * createItemKey("catalog", "category").withPrefix("api").withPrefix("v1").getPrefix;
+ * * => ["v1", "api", "catalog", "item", "category"]
+ * ```
+ */
+function createItemKey(domain: string, subDomain: string): ItemKeyChainable {
+  return buildItemKeyChainable([], domain, subDomain);
+}
+
+export { createItemKey };
+export type { ItemKeyChainable };

package/src/constants/query.listkeys.ts

@@ -0,0 +1,67 @@
+/**
+ * 列表 query key 工厂（可链式 .withPrefix）
+ * List query key factories (chainable .withPrefix).
+ */
+import type { QueryKey } from "@tanstack/react-query";
+
+import { CACHE_LIST } from "./caches";
+
+/**
+ * 链式列表 key 类型：本身即 QueryKey（数组），且带 withPrefix、getPrefix。
+ * Chainable list key type: is a QueryKey (array) and has withPrefix(), getPrefix.
+ */
+type ListKeyChainable = QueryKey & {
+  withPrefix(...prefix: unknown[]): ListKeyChainable;
+  /** 列表 key 的前缀（即完整 list key，用于 invalidation 等）。Prefix (full list key) for invalidation. */
+  getPrefix: QueryKey;
+};
+
+function buildListKeyChainable(prefix: unknown[], domain: string, subDomain: string): ListKeyChainable {
+  const key: QueryKey = [...prefix, domain, CACHE_LIST, subDomain];
+  const arr = [...key];
+
+  // 必须不可枚举：TanStack Query v5 的 partialMatchKey 会对 filter 的 queryKey 做 Object.keys；
+  // 若 withPrefix/getPrefix 可枚举，invalidateQueries({ queryKey: listKey }) 永远无法匹配 [...listKey, filter]的缓存 key。
+  Object.defineProperty(arr, "withPrefix", {
+    value(...more: unknown[]): ListKeyChainable {
+      return buildListKeyChainable([...more, ...prefix], domain, subDomain);
+    },
+    enumerable: false,
+    writable: true,
+    configurable: true,
+  });
+
+  Object.defineProperty(arr, "getPrefix", {
+    get(): QueryKey {
+      return [...key];
+    },
+    enumerable: false,
+    configurable: true,
+  });
+
+  return arr as unknown as ListKeyChainable;
+}
+
+/**
+ * 创建「列表」query key（可链式 .withPrefix）：[domain, CACHE_LIST, subDomain]
+ * Creates a list query key (chainable .withPrefix): [domain, CACHE_LIST, subDomain].
+ *
+ * @param domain - 域名。Domain name (e.g. "catalog", "auth").
+ * @param subDomain - 子域。Sub-domain (e.g. "category", "product").
+ * @returns 列表 query key（数组），带 withPrefix 可链式加前缀。List query key (array) with withPrefix for chaining.
+ * @example
+ * ```ts
+ * const key = createListKey("catalog", "category");
+ * * key => ["catalog", "list", "category"]
+ * key.getPrefix
+ * * => ["catalog", "list", "category"]
+ * createListKey("catalog", "category").withPrefix("api").withPrefix("v1").getPrefix;
+ * * => ["v1", "api", "catalog", "list", "category"]
+ * ```
+ */
+function createListKey(domain: string, subDomain: string): ListKeyChainable {
+  return buildListKeyChainable([], domain, subDomain);
+}
+
+export { createListKey };
+export type { ListKeyChainable };