lgsso-sdk 1.0.5 → 1.0.7

package/README.md

@@ -1,113 +1,163 @@
-# lgsso-sdk
-
-LG SSO登录工具库，用于处理单点登录流程、token管理和系统间跳转，支持Vue Router集成以确保路由状态同步。
-
-## 安装npm install lgsso-sdk --save
-# 或
-yarn add lgsso-sdk
-## 引入// ES模块引入
-import lgsso from 'lgsso-sdk';
-
-// CommonJS引入
-const lgsso = require('lgsso-sdk').default;
-## 初始化
-### 基础初始化// 在应用入口处初始化
-async function setupApp() {
-  const result = await lgsso.init({
-    logOutUrl: "http://lgsso2-watest.zlgx.com/",
-    tokenApi: "/v2/scm/sso/exchangeToken",
-    refreshCodeApi: "/v2/scm/sso/exchangeAccessCode",
-    logoutApi: "/v2/scm/sso/logout",
-    accessCodeKey: "accessCode",
-    tokenKey: "scm_token",
-    timeout: 8000, // 可选，默认5000ms
-    headers: {     // 可选，自定义请求头
-      'X-App-ID': 'your-application-id'
-    }
-  });
-
-  // 处理初始化结果
-  if (result.code === 0) {
-    console.log('初始化成功', result.data);
-    // 初始化完成后执行后续逻辑
-    startApplication();
-  } else {
-    console.error('初始化失败', result.msg);
-  }
-}
-
-// 启动应用
-setupApp();
-### Vue Router集成（推荐）
-为确保路由参数同步和重定向场景下的参数正确移除，建议传入Vue Router实例：
-import router from './router'; // 导入你的Vue Router实例
-
-async function setupApp() {
-  const result = await lgsso.init({
-    // ...其他配置
-    router: router, // 传入Vue Router实例
-  });
-}
-## 核心方法
-
-### 1. 获取当前tokenconst token = lgsso.getToken();
-if (token) {
-  console.log('当前token:', token);
-} else {
-  console.log('未找到token');
-}
-### 2. 退出登录async function handleLogout() {
-  const result = await lgsso.logout();
-  if (result.code !== 0) {
-    console.error('退出失败:', result.msg);
-  }
-}
-### 3. 跳转到其他系统async function goToOtherSystem() {
-  const result = await lgsso.toUrl('https://other-system.com');
-  if (result.code !== 0) {
-    console.error('跳转失败:', result.msg);
-  }
-}
-### 4. 手动删除token// 仅删除本地token，不调用退出接口
-lgsso.removeToken();
-### 5. 获取accessCode（通过token换取）async function fetchAccessCode() {
-  const result = await lgsso.getAccessCode();
-  if (result.code === 0) {
-    console.log('获取accessCode成功:', result.data);
-    // 可使用result.data进行后续操作（如拼接URL参数）
-  } else {
-    console.error('获取失败:', result.msg);
-  }
-}
-## 错误码说明
-
-| 错误码 | 说明 |
-|--------|------|
-| 0 | 成功 |
-| -100 | 初始化失败（如配置错误） |
-| -101 | 未初始化（需先调用init） |
-| -102 | 未配置logoutApi |
-| -103 | 退出失败（接口请求错误） |
-| -104 | 未提供跳转地址（toUrl方法缺少参数） |
-| -105 | 未配置refreshCodeApi |
-| -106 | 未找到有效token |
-| -107 | 跳转失败（接口请求错误） |
-| -108 | 传入的router不是有效的Vue Router实例 |
-| -200 | 非浏览器环境（调用了依赖window的方法） |
-| -201 | 响应数据格式错误 |
-| -202 | 请求超时 |
-| -203 | 网络请求失败 |
-
-## 构建与发布# 安装依赖
-npm install
-
-# 开发模式（实时监听）
-npm run dev
-
-# 构建生产版本
-npm run build
-
-# 发布到npm（需先登录）
-npm publish
-构建后会在`dist`目录生成`lgsso-sdk.js`文件，可直接引入使用。
+# lg-ssosdk
+
+LG-SSO SDK 是一个用于实现单点登录(SSO)功能的JavaScript库，提供了token管理、登录状态维护、注销、跨应用跳转等功能，方便在Web应用中快速集成SSO认证机制。
+
+## 安装
+# 使用 npm 安装
+npm install lg-ssosdk
+
+# 使用 yarn 安装
+yarn add lg-ssosdk
+## 引入方式
+// 引入默认实例
+import lgsso from 'lg-ssosdk';
+
+// 或创建自定义实例
+import { createSSO } from 'lg-ssosdk';
+const customSSO = createSSO();
+## 初始化配置
+
+使用SDK前必须先调用`init`方法进行初始化配置：
+lgsso.init({
+  accessCodeKey: 'accessCode',  // accessCode在URL中的参数名
+  tokenKey: 'scm_token',        // token在存储中的键名
+  timeout: 5000,                // 请求超时时间(毫秒)
+  headers: {},                  // 自定义请求头
+  tokenApi: '/api/token',       // 通过accessCode获取token的API地址
+  refreshCodeApi: '/api/refresh', // 刷新accessCode的API地址
+  logoutApi: '/api/logout',     // 注销API地址
+  logOutUrl: '/login',          // 登录页面URL
+  storage: localStorage,        // 存储方式(localStorage/sessionStorage)
+})
+.then(result => {
+  console.log('初始化结果:', result);
+});
+### 配置参数说明
+
+| 参数名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| accessCodeKey | String | 'accessCode' | accessCode在URL中的参数名 |
+| tokenKey | String | 'scm_token' | token在storage中的存储键名 |
+| timeout | Number | 5000 | 请求超时时间(ms) |
+| headers | Object | {} | 自定义请求头 |
+| tokenApi | String | '' | 通过accessCode获取token的API地址(必填) |
+| refreshCodeApi | String | '' | 刷新accessCode的API地址 |
+| logoutApi | String | '' | 注销API地址 |
+| logOutUrl | String | '' | 登录页面URL |
+| storage | Object | localStorage | 存储方式，需实现setItem和getItem方法 |
+
+## 核心方法
+
+### init(options)
+
+初始化SDK，合并配置并验证有效性。如果URL中存在accessCode，会自动获取token；如果没有token，会跳转到登录页。
+
+**参数**：
+- `options`：配置选项，详见初始化配置部分
+
+**返回**：`Promise<Object>` - 初始化结果
+
+### getToken()
+
+获取存储的token值。
+
+**返回**：`String|null` - token值或null
+const token = lgsso.getToken();
+console.log('当前token:', token);
+### removeToken()
+
+删除存储的token。
+lgsso.removeToken();
+### logout()
+
+退出登录，调用logoutApi并清除token，然后跳转到登录页。
+
+**返回**：`Promise<Object>` - 退出结果
+lgsso.logout()
+.then(result => {
+  console.log('退出结果:', result);
+});
+### toUrl(redirectUrl)
+
+使用当前token换取新的accessCode，并跳转到指定URL（自动在URL后添加accessCode参数）。
+
+**参数**：
+- `redirectUrl`：目标跳转地址
+
+**返回**：`Promise<Object>` - 操作结果
+lgsso.toUrl('https://example.com/target')
+.then(result => {
+  console.log('跳转准备结果:', result);
+});
+### getAccessCode()
+
+使用当前token换取新的accessCode。
+
+**返回**：`Promise<Object>` - 包含accessCode的结果（在data字段中）
+lgsso.getAccessCode()
+.then(result => {
+  if (result.code === 0) {
+    console.log('新的accessCode:', result.data);
+  }
+});
+### getConfig()
+
+获取当前配置的副本。
+
+**返回**：`Object|null` - 当前配置
+const config = lgsso.getConfig();
+console.log('当前配置:', config);
+## 错误码说明
+
+| 错误码 | 说明 |
+|--------|------|
+| -100 | 初始化相关错误（如缺少配置、配置无效等） |
+| -101 | 未初始化（需先调用init方法） |
+| -102 | 未配置logoutApi |
+| -103 | 退出登录失败 |
+| -104 | 跳转地址为空 |
+| -105 | 未配置refreshCodeApi |
+| -106 | 未找到有效token |
+| -107 | 跳转失败 |
+| -200 | 非浏览器环境使用request方法 |
+| -201 | 响应数据不是有效的JSON格式 |
+| -202 | 请求超时 |
+| -203 | 网络请求失败 |
+
+## 使用示例
+// 初始化SDK
+lgsso.init({
+  tokenApi: '/api/getToken',
+  refreshCodeApi: '/api/refreshCode',
+  logoutApi: '/api/logout',
+  logOutUrl: '/login'
+})
+.then(initResult => {
+  console.log('初始化结果:', initResult);
+  
+  // 获取token
+  const token = lgsso.getToken();
+  console.log('当前token:', token);
+  
+  // 跳转到其他应用
+  document.getElementById('gotoOtherApp').addEventListener('click', () => {
+    lgsso.toUrl('https://other-app.example.com')
+      .catch(err => console.error('跳转失败:', err));
+  });
+  
+  // 退出登录
+  document.getElementById('logoutBtn').addEventListener('click', () => {
+    lgsso.logout()
+      .catch(err => console.error('退出失败:', err));
+  });
+})
+.catch(err => {
+  console.error('初始化失败:', err);
+});
+## 注意事项
+
+1. 必须先调用`init`方法初始化后才能使用其他方法
+2. `tokenApi`是必填配置项，用于通过accessCode获取token
+3. 在非浏览器环境下使用时，部分依赖浏览器API的功能将不可用
+4. 建议在应用入口处进行初始化，确保整个应用生命周期中都能使用SSO功能