@workfly/wf-types 0.1.0

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@workfly/wf-types",
+  "version": "0.1.0",
+  "description": "WorkFly 小程序全局 wf SDK 的 TypeScript 类型（由 src/shared/wf-api.ts 经 scripts/gen-wf-types.mjs 生成）。模板工程 devDependency 引入后 tsconfig types 即可拿到全局 wf。",
+  "types": "wf.d.ts",
+  "files": [
+    "wf.d.ts"
+  ],
+  "keywords": [
+    "workfly",
+    "miniapp",
+    "wf",
+    "types"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT"
+}

package/wf.d.ts

@@ -0,0 +1,474 @@
+// 【自动生成，请勿手改】WorkFly 小程序 SDK 类型声明。
+// 源：src/shared/wf-api.ts；重新生成：node scripts/gen-wf-types.mjs
+// bundle（专业版）小程序把本文件放进工程即可全量 wf 类型；sandbox 直接用全局 wf。
+/** 异步 API 的 wx 风格回调（与 Promise 双模并存）。`R` 为成功结果业务字段。 */
+export interface WxCallbacks<R> {
+  /** 成功回调，入参为业务结果 + `errMsg: '<api>:ok'`。 */
+  success?: (res: R & { errMsg: string }) => void
+  /** 失败回调，入参为 `{ errMsg: '<api>:fail <reason>' }`。 */
+  fail?: (err: { errMsg: string }) => void
+  /** 结束回调，成功失败都触发。 */
+  complete?: (res: { errMsg: string }) => void
+}
+
+/** 异步 API 的入参 = 业务参数 + 回调。 */
+export type WxAsync<A, R> = A & WxCallbacks<R>
+
+// ── 网络 ──────────────────────────────────────────────────────────────────────
+
+/** {@link WF.request} 入参。字段对齐 wx：用 header / data / method（非 headers / body）。 */
+export interface RequestOptions {
+  /** 目标 URL。 */
+  url: string
+  /** HTTP 方法，默认 GET。 */
+  method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS'
+  /** 请求头。 */
+  header?: Record<string, string>
+  /** 请求体；对象会自动 JSON 序列化并补 Content-Type: application/json。 */
+  data?: string | Record<string, unknown>
+  /** 响应体解析方式，默认 'json'（自动 JSON.parse）。 */
+  dataType?: 'json' | 'text'
+  /** 超时毫秒数。 */
+  timeout?: number
+}
+
+/** {@link WF.request} 返回。字段对齐 wx：data / statusCode / header。 */
+export interface RequestResult {
+  /** 响应体（dataType:'json' 时为解析后的对象）。 */
+  data: unknown
+  /** HTTP 状态码。 */
+  statusCode: number
+  /** 响应头。 */
+  header: Record<string, string>
+}
+
+// ── 存储 ──────────────────────────────────────────────────────────────────────
+
+/** {@link WF.setStorage} 入参。 */
+export interface SetStorageOptions {
+  /** 键名。 */
+  key: string
+  /** 值，任意可 JSON 序列化的数据。 */
+  data: unknown
+  /** 为 true 时加密落盘（走宿主 Vault），需声明 `vault` 权限。默认 false（明文）。 */
+  encrypt?: boolean
+}
+
+/** {@link WF.getStorage} 入参。 */
+export interface GetStorageOptions {
+  /** 键名。 */
+  key: string
+  /** 与写入时一致：true 从加密存储读。默认 false。 */
+  encrypt?: boolean
+}
+
+/** 存储概况。 */
+export interface StorageInfo {
+  /** 当前所有键名。 */
+  keys: string[]
+  /** 当前占用（KB，估算）。 */
+  currentSize: number
+  /** 上限（KB）。 */
+  limitSize: number
+}
+
+// ── 剪贴板 ────────────────────────────────────────────────────────────────────
+
+/** {@link WF.setClipboardData} 入参。 */
+export interface SetClipboardDataOptions {
+  /** 写入剪贴板的文本。 */
+  data: string
+}
+
+// ── UI 交互 ───────────────────────────────────────────────────────────────────
+
+/** {@link WF.showToast} 入参。 */
+export interface ToastOptions {
+  /** 提示文案。 */
+  title: string
+  /** 图标，默认 success。 */
+  icon?: 'success' | 'error' | 'loading' | 'none'
+  /** 停留毫秒数，默认 1500。 */
+  duration?: number
+  /** 是否显示透明蒙层防穿透，默认 false。 */
+  mask?: boolean
+}
+
+/** {@link WF.showLoading} 入参。 */
+export interface LoadingOptions {
+  /** 加载文案。 */
+  title: string
+  /** 是否显示蒙层，默认 false。 */
+  mask?: boolean
+}
+
+/** {@link WF.showModal} 入参。 */
+export interface ModalOptions {
+  /** 标题。 */
+  title?: string
+  /** 正文内容。 */
+  content?: string
+  /** 是否显示取消按钮，默认 true。 */
+  showCancel?: boolean
+  /** 取消按钮文案，默认「取消」。 */
+  cancelText?: string
+  /** 确认按钮文案，默认「确定」。 */
+  confirmText?: string
+}
+
+/** {@link WF.showModal} 返回。 */
+export interface ModalResult {
+  /** 用户点了确认。 */
+  confirm: boolean
+  /** 用户点了取消（或蒙层关闭）。 */
+  cancel: boolean
+}
+
+/** {@link WF.showActionSheet} 入参。 */
+export interface ActionSheetOptions {
+  /** 选项文案列表。 */
+  itemList: string[]
+  /** 选项文字颜色。 */
+  itemColor?: string
+}
+
+/** {@link WF.previewImage} 入参。 */
+export interface PreviewImageOptions {
+  /** 要预览的图片地址列表。 */
+  urls: string[]
+  /** 当前显示的图片地址，默认 urls[0]。 */
+  current?: string
+}
+
+// ── 启动 / 系统 ───────────────────────────────────────────────────────────────
+
+/** {@link WF.getLaunchOptionsSync} 返回。 */
+export interface LaunchOptions {
+  /** 启动路径（小程序内部路由，预留）。 */
+  path: string
+  /** 启动携带的参数（deeplink / 剪贴板提示 / IM 内容匹配带入，如 { curl }）。 */
+  query: Record<string, unknown>
+  /** 启动场景（panel / spotlight / deeplink / im）。 */
+  scene: string
+}
+
+/** {@link WF.getSystemInfoSync} 返回。 */
+export interface SystemInfo {
+  /** 宿主平台标识，固定 'workfly'。 */
+  platform: 'workfly'
+  /** 当前主题，跟随宿主暗 / 亮。 */
+  theme: 'dark' | 'light'
+  /** 宿主应用版本。 */
+  version: string
+  /** 界面语言（如 'zh-CN'）。 */
+  language: string
+}
+
+// ── BIP 生态扩展 ──────────────────────────────────────────────────────────────
+
+/** {@link BipNamespace.rsaEncrypt} 入参。 */
+export interface RsaEncryptOptions {
+  /** PEM 格式公钥（调用方自带）。 */
+  publicKey: string
+  /** 待加密明文。 */
+  data: string
+  /** 填充模式，默认 pkcs1（对齐 Java Cipher.getInstance("RSA")）。 */
+  padding?: 'pkcs1' | 'oaep'
+}
+
+/** {@link BipNamespace.rsaEncrypt} 返回。 */
+export interface RsaEncryptResult {
+  /** base64 编码的密文。 */
+  data: string
+}
+
+/**
+ * `wf.bip.*` —— BIP 生态扩展区。
+ *
+ * `wf.*` 是对标 wx 的可移植标准面（与 BIP 无关）；本命名空间是 WorkFly 作为用友 BIP
+ * 客户端特有的、wx 没有的业务能力，统一围进此处，不污染标准面（先例：wx.cloud.*）。
+ */
+export interface BipNamespace {
+  /**
+   * RSA 公钥加密（wx 无等价的 BIP 生态扩展）。
+   *
+   * 当前服务 BIP 系 OAuth 握手：包内拼 `clientSecret:秒级时间戳` 后调用本方法得到
+   * base64 密文，再走授权码链路。公钥由调用方传入，宿主不知用途。
+   *
+   * @status stable
+   * @example
+   * const { data } = await wf.bip.rsaEncrypt({
+   *   publicKey,
+   *   data: 'secret:' + Math.floor(Date.now() / 1000)
+   * })
+   */
+  rsaEncrypt(opts: WxAsync<RsaEncryptOptions, RsaEncryptResult>): Promise<RsaEncryptResult>
+}
+
+// ── 顶层 WF 接口 ──────────────────────────────────────────────────────────────
+
+/**
+ * WorkFly 小程序 SDK 全局对象 `wf`（对标微信 `wx`）。
+ *
+ * - sandbox 形态：`window.wf`
+ * - bundle 形态：全局 `wf`，且挂载函数 `mount(el, ctx)` 的 `ctx` 指向同一对象。
+ */
+export interface WF {
+  // —— 网络 ——
+  /**
+   * 发起 HTTP 请求（经主进程代理，绕 CORS、可直发任意头）。
+   * @status stable
+   * @example
+   * const res = await wf.request({
+   *   url: 'https://api.example.com/items',
+   *   method: 'GET'
+   * })
+   * console.log(res.statusCode, res.data)
+   */
+  request(opts: WxAsync<RequestOptions, RequestResult>): Promise<RequestResult>
+
+  // —— 存储（异步） ——
+  /**
+   * 写入本地存储。`encrypt:true` 时加密落盘（Vault）。
+   * @status stable
+   * @example
+   * await wf.setStorage({
+   *   key: 'items',
+   *   data: list
+   * })
+   * // encrypt:true 走加密存储（需 vault 权限）
+   * await wf.setStorage({
+   *   key: 'token',
+   *   data: token,
+   *   encrypt: true
+   * })
+   */
+  setStorage(opts: WxAsync<SetStorageOptions, void>): Promise<void>
+  /**
+   * 读取本地存储。
+   * @status stable
+   * @example
+   * const { data } = await wf.getStorage({
+   *   key: 'items'
+   * })
+   */
+  getStorage(opts: WxAsync<GetStorageOptions, { data: unknown }>): Promise<{ data: unknown }>
+  /**
+   * 删除指定键。
+   * @status stable
+   * @example
+   * await wf.removeStorage({
+   *   key: 'items'
+   * })
+   */
+  removeStorage(opts: WxAsync<{ key: string }, void>): Promise<void>
+  /**
+   * 清空本小程序的全部存储。
+   * @status stable
+   * @example
+   * await wf.clearStorage()
+   */
+  clearStorage(opts?: WxCallbacks<void>): Promise<void>
+  /**
+   * 获取存储概况。
+   * @status stable
+   * @example
+   * const { keys, currentSize, limitSize } = await wf.getStorageInfo()
+   */
+  getStorageInfo(opts?: WxCallbacks<StorageInfo>): Promise<StorageInfo>
+
+  // —— 存储（同步） ——
+  /**
+   * 同步写入本地存储。
+   * @status stable
+   * @example
+   * wf.setStorageSync('count', 1)
+   * // 第三参数 encrypt:true 加密落盘
+   * wf.setStorageSync('token', token, true)
+   */
+  setStorageSync(key: string, data: unknown, encrypt?: boolean): void
+  /**
+   * 同步读取本地存储。
+   * @status stable
+   * @example
+   * const count = wf.getStorageSync('count')
+   */
+  getStorageSync(key: string, encrypt?: boolean): unknown
+  /**
+   * 同步删除指定键。
+   * @status stable
+   * @example
+   * wf.removeStorageSync('count')
+   */
+  removeStorageSync(key: string): void
+  /**
+   * 同步清空全部存储。
+   * @status stable
+   * @example
+   * wf.clearStorageSync()
+   */
+  clearStorageSync(): void
+  /**
+   * 同步获取存储概况。
+   * @status stable
+   * @example
+   * const { keys, currentSize, limitSize } = wf.getStorageInfoSync()
+   */
+  getStorageInfoSync(): StorageInfo
+
+  // —— 剪贴板 ——
+  /**
+   * 写入系统剪贴板。
+   * @status stable
+   * @example
+   * await wf.setClipboardData({
+   *   data: 'Hello WorkFly'
+   * })
+   */
+  setClipboardData(opts: WxAsync<SetClipboardDataOptions, void>): Promise<void>
+  /**
+   * 读取系统剪贴板文本。
+   * @status stable
+   * @example
+   * const { data } = await wf.getClipboardData()
+   */
+  getClipboardData(opts?: WxCallbacks<{ data: string }>): Promise<{ data: string }>
+
+  // —— UI 交互（宿主渲染） ——
+  /**
+   * 显示消息提示框。
+   * @status stable
+   * @example
+   * await wf.showToast({
+   *   title: '已保存',
+   *   icon: 'success'
+   * })
+   */
+  showToast(opts: WxAsync<ToastOptions, void>): Promise<void>
+  /**
+   * 隐藏消息提示框。
+   * @status stable
+   * @example
+   * await wf.hideToast()
+   */
+  hideToast(opts?: WxCallbacks<void>): Promise<void>
+  /**
+   * 显示加载提示框（需配对 hideLoading）。
+   * @status stable
+   * @example
+   * await wf.showLoading({
+   *   title: '加载中…'
+   * })
+   * // 完成后务必配对 hideLoading
+   * await wf.hideLoading()
+   */
+  showLoading(opts: WxAsync<LoadingOptions, void>): Promise<void>
+  /**
+   * 隐藏加载提示框。
+   * @status stable
+   * @example
+   * await wf.hideLoading()
+   */
+  hideLoading(opts?: WxCallbacks<void>): Promise<void>
+  /**
+   * 显示模态对话框。
+   * @status stable
+   * @example
+   * const { confirm } = await wf.showModal({
+   *   title: '删除',
+   *   content: '确定删除？'
+   * })
+   * if (confirm) {
+   *   // 执行删除
+   * }
+   */
+  showModal(opts: WxAsync<ModalOptions, ModalResult>): Promise<ModalResult>
+  /**
+   * 显示底部操作菜单。
+   * @status stable
+   * @example
+   * const { tapIndex } = await wf.showActionSheet({
+   *   itemList: ['编辑', '删除']
+   * })
+   */
+  showActionSheet(
+    opts: WxAsync<ActionSheetOptions, { tapIndex: number }>
+  ): Promise<{ tapIndex: number }>
+  /**
+   * 全屏预览图片（复用宿主看图窗口）。
+   * @status stable
+   * @example
+   * await wf.previewImage({
+   *   urls: ['https://example.com/a.png', 'https://example.com/b.png']
+   * })
+   */
+  previewImage(opts: WxAsync<PreviewImageOptions, void>): Promise<void>
+
+  // —— 启动 / 系统 ——
+  /**
+   * 同步获取小程序启动参数（场景、携带 query）。
+   * @status stable
+   * @example
+   * const { path, query, scene } = wf.getLaunchOptionsSync()
+   * // query 带入 deeplink / 剪贴板 / IM 内容匹配的参数
+   */
+  getLaunchOptionsSync(): LaunchOptions
+  /**
+   * 同步获取本次再进入的参数（deeplink / IM 二次唤起）。
+   * @status stable
+   * @example
+   * const opts = wf.getEnterOptionsSync()
+   */
+  getEnterOptionsSync(): LaunchOptions
+  /**
+   * 同步获取宿主系统信息（平台、主题、版本、语言）。
+   * @status stable
+   * @example
+   * const { platform, theme, version, language } = wf.getSystemInfoSync()
+   */
+  getSystemInfoSync(): SystemInfo
+
+  // —— BIP 生态扩展 ——
+  /** BIP 生态扩展命名空间，详见 {@link BipNamespace}。 */
+  bip: BipNamespace
+}
+
+// ── bundle 形态挂载契约（与宿主 BundleHost 对齐）──────────────────────────────────
+
+/** 小程序清单的最小可见面（bundle 运行时拿得到的 app 元信息）。 */
+export interface MiniAppManifest {
+  id: string
+  name: string
+  version: string
+  ui: {
+    standalone: {
+      enabled: true
+      entry: string
+      render?: 'webview' | 'sandbox' | 'bundle'
+      layout?: 'full' | 'split'
+    }
+  }
+  permissions?: ({ id: string; reason: string } | string)[]
+  [k: string]: unknown
+}
+
+/** 宿主传给挂载函数的上下文；`ctx.wf` 与全局 `wf` 是同一对象。 */
+export interface BundleCtx {
+  app: MiniAppManifest
+  wf: WF
+  /** 返回上一层（关闭本小程序视图）。 */
+  onBack: () => void
+  /** deeplink / 剪贴板 / IM 内容带入的启动 payload（如 { curl }），可据此预填。 */
+  launchPayload?: Record<string, unknown> | null
+}
+
+/** bundle 入口默认导出的「挂载函数」：在宿主给的 el 内自建一棵树，返回 unmount。 */
+export type BundleMount = (el: HTMLElement, ctx: BundleCtx) => () => void
+
+declare global {
+  /** 宿主注入的小程序 SDK（sandbox: window.wf；bundle: 全局 wf 与 ctx.wf 同一对象）。 */
+  const wf: WF
+  interface Window {
+    wf: WF
+  }
+}