@jctrans-materials/shared 1.0.37-beta.20 → 1.0.37-beta.22

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import { AxiosInstance } from 'axios';
 import { Emitter } from 'mitt';
 
 declare type ActionKeys = (typeof MODAL_ACTION)[keyof typeof MODAL_ACTION];
@@ -94,6 +95,18 @@ export declare function checkMobileCodeApi(data: {
 
 export declare function clearAllAuth(): void;
 
+/**
+ * 清除 clientId（用于登出等场景）
+ */
+export declare function clearClientId(): void;
+
+export declare interface ClientIdPluginOptions {
+    /**
+     * 自定义 header 名称，默认值：'client-uid'
+     */
+    headerName?: string;
+}
+
 export declare interface CommonParams {
     current?: number;
     size?: number;
@@ -130,6 +143,23 @@ export declare function completeJoinCompanyRedirectApi(data: any): Promise<any>;
  */
 export declare type ConfigCallback<T = GioConfigValue> = (value: T) => void;
 
+/**
+ * 创建一个 fetch 拦截器函数
+ * 返回一个包装后的 fetch，会自动注入 clientId
+ *
+ * @param options 配置选项
+ * @returns 返回一个新的 fetch 函数
+ *
+ * @example
+ * // 在 Nuxt 插件中使用
+ * import { createFetchWithClientId } from '@jctrans-materials/shared'
+ *
+ * export default defineNuxtPlugin(() => {
+ *   const $fetch = createFetchWithClientId()
+ * })
+ */
+export declare function createFetchWithClientId(options?: FetchClientIdOptions): typeof fetch;
+
 export declare function createRequest(driver: RequestDriver, options?: RequestOptions): RequestAdapter;
 
 export declare const currentConfig: {
@@ -168,6 +198,21 @@ export declare const ExpiresInKey = "JC-Expires-In";
 
 export declare const ExpiresInTimeKey = "JC-Expires-Time-In";
 
+/**
+ * Fetch API ClientId 拦截器
+ * 用于在 fetch 请求中自动注入 clientId header
+ */
+export declare interface FetchClientIdOptions {
+    /**
+     * 自定义 header 名称，默认值：'client-uid'
+     */
+    headerName?: string;
+    /**
+     * 是否在请求中注入 (默认 true)
+     */
+    injectRequest?: boolean;
+}
+
 /**
  * 获取字典列表
  * @param data
@@ -193,6 +238,18 @@ export declare function findPAreaCodeAPi(data?: {
     size: number;
 }): Promise<any>;
 
+/**
+ * ClientId 管理工具
+ * 用于生成和管理唯一的客户端标识符
+ * 使用 nanoid 生成，完全 SSR 兼容
+ * 策略：localStorage → sessionStorage → nanoid
+ */
+/**
+ * 生成唯一的客户端 ID
+ * 使用 nanoid，完全 SSR 兼容
+ */
+export declare function generateClientId(): string;
+
 export declare function getAirport(params?: {
     page?: number;
     size?: number;
@@ -261,6 +318,11 @@ export declare function getCountry(params?: {
     ids?: number[];
 }): Promise<BaseResponse<UnifiedItem>>;
 
+/**
+ * 获取当前的 clientId（不会创建新的）
+ */
+export declare function getCurrentClientId(): string | null;
+
 /**
  * 🚀 补全：获取 Access Token 的过期时间戳 (用于判断是否需要刷新)
  */
@@ -328,6 +390,12 @@ export declare function getMobileEmailApi(data: {
     id: string;
 }): Promise<any>;
 
+/**
+ * 获取或生成 clientId
+ * 优先级: localStorage → sessionStorage → 生成新 nanoid
+ */
+export declare function getOrCreateClientId(): string;
+
 /**
  * 跨环境获取 Path
  */
@@ -419,6 +487,8 @@ export declare function getTracker<T extends GioTracker>(trackerInstance?: T): T
  */
 export declare function getUserInfoApi(data: any): Promise<any>;
 
+export declare const GIO_CLICK_PAGE_REQUIRED_FIELDS: readonly ["companyID_var", "contactPerson_var", "inquiryID_var", "modulePosition_var", "moduleType_var", "pageCode_var", "pageClickName_var", "moduleName_var"];
+
 /**
  * GIO 属性对象
  */
@@ -541,6 +611,50 @@ export declare interface GioPageProps {
  */
 export declare type GioTimerId = string;
 
+/**
+ * GrowingIO SDK 封装模块
+ * 基于 gio-webjs-sdk npm 包
+ *
+ * @module gio
+ *
+ * @example
+ * ```typescript
+ * import { tracker, type GioAttributes, type GioInitOptions } from '@jctrans-materials/shared';
+ *
+ * // 基础初始化
+ * tracker.init('your-account-id', 'your-datasource-id', {
+ *   debug: true,
+ *   trackPage: false,
+ * });
+ *
+ * // 微信公众号 H5（需要 appId 和 forceLogin）
+ * tracker.init('accountId', 'dataSourceId', 'wx-app-id', {
+ *   forceLogin: true,
+ *   debug: true,
+ * });
+ *
+ * // 设置登录用户 ID
+ * tracker.setUserId('user-123');
+ * tracker.setUserId('user-123', 'user_id', () => {
+ *   console.log('set user id with userKey done');
+ * });
+ *
+ * // 埋点事件
+ * tracker.track('order_submit', {
+ *   order_type: 'freight',
+ *   price: 5000,
+ *   services: ['ocean', 'customs']
+ * });
+ *
+ * // 设置全局属性
+ * tracker.setGeneralProps({
+ *   platform: 'jctrans_web',
+ *   locale: 'zh-CN'
+ * });
+ * ```
+ */
+export declare type GioTrackAttrs = Record<string, string | number | Array<string | number> | null | undefined>;
+
 declare class GioTracker {
     private hasInitCalled;
     private dispatcher;
@@ -761,6 +875,30 @@ export declare const HasLoginKey = "hasLogin";
  */
 export declare const initSharedConfig: (newConfig: Partial<SharedConfig>) => void;
 
+/**
+ * 为 axios 实例添加 clientId 拦截器
+ * @param instance axios 实例
+ * @param options 配置选项
+ */
+export declare function installClientIdPlugin(instance: AxiosInstance, options?: ClientIdPluginOptions): void;
+
+/**
+ * 在全局 fetch 上安装 clientId 拦截器
+ * 仅用于客户端环境，会覆盖全局 fetch
+ *
+ * @param options 配置选项
+ *
+ * @example
+ * import { installFetchClientId } from '@jctrans-materials/shared'
+ *
+ * export default defineNuxtPlugin(() => {
+ *   if (process.client) {
+ *     installFetchClientId()
+ *   }
+ * })
+ */
+export declare function installFetchClientId(options?: FetchClientIdOptions): void;
+
 /**
  * 获取邀请加入公司信息
  * @param data
@@ -772,6 +910,13 @@ declare interface IResponse<T> {
     data: T;
 }
 
+/**
+ * 检查值是否为空
+ * @param value 要检查的值
+ * @returns 是否为空
+ */
+export declare function isEmpty(value: any): boolean;
+
 /**
  * 检查 GIO 是否可用（浏览器环境且已初始化）
  *
@@ -1024,27 +1169,17 @@ export declare interface LocationUnifiedItem {
     display?: string;
     displayEn?: string;
     displayCn?: string;
-    /** * 通用代码字段 (自动取 scacCode 或 carrierCode)
-     * 适用于仅展示用途
-     */
     code?: string;
-    /** * SCAC 代码 (Standard Carrier Alpha Code) - 通常用于船司
-     */
     scacCode?: string;
-    /** * IATA 代码 - 通常用于航司
-     */
     iataCode?: string;
-    /** * 承运人通用代码
-     */
     carrierCode?: string;
-    /** * 承运人类型: 'air' | 'shipping'
-     */
     lineType?: string;
     continent?: Record<string, any>;
     country?: Record<string, any>;
     city?: Record<string, any>;
     province?: Record<string, any>;
     raw?: any;
+    [key: string]: unknown;
 }
 
 /**
@@ -1085,6 +1220,8 @@ export declare function loginByQrCode(data: {
     appId: string;
     redirectPath: string;
     kick: boolean;
+    prjId?: string;
+    formEntry?: string;
 }): Promise<any>;
 
 /**
@@ -1143,6 +1280,10 @@ export declare type ModalEvents = Record<ActionKeys, any> & {
 
 export declare type ModalOpenCallback = () => void;
 
+export declare const normalizeAttrs: (attrs?: GioTrackAttrs) => GioTrackAttrs;
+
+export declare const normalizeClickPageAttrs: (eventName: string, attrs?: GioTrackAttrs) => GioTrackAttrs;
+
 /**
  * 页面变更回调
  */
@@ -1215,7 +1356,7 @@ export declare interface reportNewTypeData {
 
 export declare function reportNewTypeDataApi(payload: reportNewTypeData): Promise<{}>;
 
-export declare type ReportType = "City" | "Seaport" | "Airport" | "Line";
+export declare type ReportType = "City" | "Seaport" | "Airport" | "Line" | "Carrier" | "shipping_line" | "shipping_carrier" | "air_line" | "air_carrier";
 
 declare interface RequestAdapter {
     get(url: string, config?: RequestConfig): Promise<any>;
@@ -1254,6 +1395,16 @@ export declare function resetGioSessionItems(): void;
  */
 export declare function resetPasswordApi(data: any): Promise<any>;
 
+/**
+ * 保存 clientId 到 localStorage
+ */
+export declare function saveClientIdToLocalStorage(clientId: string): void;
+
+/**
+ * 保存 clientId 到 sessionStorage
+ */
+export declare function saveClientIdToSessionStorage(clientId: string): void;
+
 /**
  * 统一搜索接口
  * - 支持 keyword（模糊）, displayInfo（数组）, ids（按 type）, scope（countryId/cityId/provinceId）