@jt-home/sdk-tools

@jt-home/sdk-tools 是面向外部项目的聚合入口包，负责统一导出常用认证、请求、路由、事件、时间和宿主环境工具。

提供的入口

• @jt-home/sdk-tools
• @jt-home/sdk-tools/auth
• @jt-home/sdk-tools/request-http
• @jt-home/sdk-tools/event-bus
• @jt-home/sdk-tools/router

设计目标

• 对外只装一个包，也能拿到常用的认证、请求、路由和事件能力。
• 主入口沉淀跨业务的轻量工具能力，例如时区转换和飞书工作台外部浏览器打开。
• 保留子路径导入，方便按需引用。
• 入口只做显式导出，不使用 export *。

示例

import { createAxios, authRoutePlugin } from "@jt-home/sdk-tools";

const http = createAxios({
  baseURL: "/api",
});

时区工具

接口说明

interface ConvertTimeZoneApi {
  (
    time: string,
    fromTimeZone: string,
    toTimeZone: string,
    format?: string,
    focus?: boolean,
  ): string;
}

interface UtcToLocalTimeApi {
  (
    utcTime: string,
    localTimeZone?: string,
    format?: string,
    focus?: boolean,
  ): string;
}

interface LocalTimeToUtcApi {
  (
    localTime: string,
    localTimeZone?: string,
    format?: string,
    focus?: boolean,
  ): string;
}

参数说明：

• time / utcTime / localTime：要格式化或转换的时间字符串。
• fromTimeZone：原始时区，例如 Asia/Shanghai、UTC、UTC+08:00。
• toTimeZone / localTimeZone：目标时区或本地时区，例如 America/New_York。
• format：输入和输出共用的格式，默认 YYYY-MM-DD HH:mm:ss。
• focus：日期-only 默认不转换；传 true 时强制转换。

import {
  convertTimeZone,
  getCurrentTimeZone,
  localTimeToUtc,
  utcToLocalTime,
} from "@jt-home/sdk-tools";

getCurrentTimeZone(); // Asia/Shanghai
convertTimeZone("2026/06/09 08:30", "Asia/Shanghai", "America/New_York", "YYYY/MM/DD HH:mm");
utcToLocalTime("2026-06-09 00:30:00", "Asia/Shanghai");
localTimeToUtc("2026-06-09 08:30:00", "Asia/Shanghai");
convertTimeZone("2026-06-09", "Asia/Shanghai", "America/New_York", "YYYY-MM-DD", true);

• 默认格式为 YYYY-MM-DD HH:mm:ss。
• convertTimeZone 会按传入格式解析输入，并用同一格式输出。
• 只有日期没有时分秒时默认原样返回；传 focus=true 时会强制转换。
• 时区支持 IANA 名称（如 Asia/Shanghai）和固定偏移（如 UTC+08:00、+08）。

飞书工作台外部浏览器

openFeishuWorkbenchPage(targetUrl, options?) 用于飞书工作台和普通浏览器共用同一套跳转入口。普通浏览器中直接跳转目标页面；飞书工作台内读取 localStorage 里的 refresh_token，拼接 token、source=feishu_sso、lk_jump_to_browser=true 后交给 window.tt.openSchema 在外部浏览器打开。返回结果里的 handled 只表示 SDK 已完成跳转或已交给飞书处理，缺少 refresh_token 或 openSchema 不可用时会返回 handled: false，调用方可继续走原有内部跳转。

import {
  buildFeishuWorkbenchBrowserUrl,
  isFeishuClient,
  openFeishuWorkbenchPage,
} from "@jt-home/sdk-tools";

const result = await openFeishuWorkbenchPage("/hrpt/personnel");

• isFeishuClient(userAgent?)：判断当前 UA 是否来自飞书或 Lark 客户端。
• buildFeishuWorkbenchBrowserUrl(targetUrl, token, options?)：拼接 token、source=feishu_sso 和 lk_jump_to_browser=true，并按 origin 生成外部浏览器可打开的绝对地址。
• buildFeishuWorkbenchPageUrl(targetUrl, options?)：生成普通浏览器直接跳转地址。
• openFeishuWorkbenchPage(targetUrl, options?)：非飞书环境直接跳转目标页；飞书环境读取 refresh_token 后通过 window.tt.openSchema({ schema: url, external: true }) 打开外部浏览器；失败时返回 handled: false。
• openFeishuWorkbenchBrowser(targetUrl, options?)：保留兼容旧名称，行为同 openFeishuWorkbenchPage。