@zleap-ai/app-sdk 0.0.0-stage → 0.10.0

package/dist/types/zleap-sdk-types.d.ts

@@ -0,0 +1,138 @@
+/** @generated from packages/shared/src/apps/appSdkTypes.ts; do not edit.
+ * Source SHA-256: fae9b1c73efa81131d6a13d0dfc76476705c449930587116c4814c2591646dca
+ * Rebuild with: node scripts/build-app-sdk.mjs
+ */
+/**
+ * @zleap/app-sdk 纯类型模块 —— 社交域 / 邀请域契约类型（自 appSdk.ts 拆出）。
+ *
+ * 拆分原因（2026-09-17 Lzm）：单文件 700 行上限规则 —— appSdk.ts 逼近上限，
+ * 而本模块**仅含类型**（零运行时代码），appSdk.ts 以 `import type` 引用并
+ * re-export；经 build-app-sdk.mjs 类型擦除后产物依然零 import，自包含硬约束不破。
+ * 类型与 hostSocial.ts / appInvite.ts / hostCapabilities.tsx 保持**结构同形**
+ * （漂移由 appSdk.test.ts 的互赋值断言拦截）。
+ *
+ * 编码：utf8 | 语言：TypeScript | 作者：Lzm | 日期：2026-09-17
+ */
+/** APP 私有对象分享卡片（与后端 `ShareCreate.app_object` 结构白名单同口径） */
+export interface AppShareCardInput {
+  /** 卡片标题（必填 ≤100 字，服务端 trim） */
+  title: string;
+  /** 卡片摘要（可选 ≤500 字） */
+  summary?: string;
+  /** 图标（可选；必须平台自托管路径 `/api/v1/…`，缺省回退应用图标） */
+  icon_url?: string;
+  /** 点卡启动参数（必填，8 键 × 键≤32 × 值≤256；平台不解释语义） */
+  object_ref: Record<string, string>;
+}
+/** 选人返回的主体 */
+export interface SocialPeer {
+  id: string;
+  name: string;
+  avatarUrl?: string | null;
+  /** 主体类型：user / agent */
+  type?: 'user' | 'agent';
+}
+/** 选会话返回的会话 */
+export interface SocialConversation {
+  id: string;
+  name: string;
+  /** 外部 IM 平台标识；非空表示外部会话（分享卡片会 409，选会话时应禁用该行） */
+  externalPlatform?: string | null;
+}
+export interface SocialFollowResult {
+  ok: boolean;
+  /** 操作后的关注状态（follow → true；unfollow → false） */
+  following: boolean;
+}
+export interface SocialShareResult {
+  ok: boolean;
+  /** 失败的目标数量（shareToConversation 按会话扇出时可能部分失败） */
+  failedCount: number;
+}
+export interface SocialCreateGroupResult {
+  ok: boolean;
+  conversationId?: string;
+}
+/**
+ * 社交宿主能力面：关注 / 选人 / 建群 / 分享（规范 §6.5）。
+ * 分享的 `appId` 由宿主层强制注入/覆盖，调用方传入不生效（D1 身份锚定）。
+ */
+export interface HostSocial {
+  /** 关注（单向，无需对方同意；黑名单拦截） */
+  follow(targetId: string, targetType?: 'user' | 'agent'): Promise<SocialFollowResult>;
+  /** 取关（单向） */
+  unfollow(targetId: string, targetType?: 'user' | 'agent'): Promise<SocialFollowResult>;
+  /** 是否已关注 */
+  isFollowing(targetId: string, targetType?: 'user' | 'agent'): Promise<boolean>;
+  /** 平台选人组件：返回用户选中的主体（单/多选）；APP 不再自造通讯录 */
+  pickUsers(options?: { multiple?: boolean; excludeUserIds?: string[] }): Promise<SocialPeer[]>;
+  /** 平台选会话组件：返回用户选中的会话（用于分享） */
+  pickConversations(options?: { multiple?: boolean }): Promise<SocialConversation[]>;
+  /** 分享：按会话扇出落卡片消息（`app_object` 形态） */
+  shareToConversation(input: {
+    card: AppShareCardInput;
+    conversationIds: string[];
+    appId?: string;
+  }): Promise<SocialShareResult>;
+  /** 分享：发布为动态（作者 = 当前用户） */
+  shareToDynamic(input: {
+    card: AppShareCardInput;
+    visibility?: 'public' | 'friend' | 'private';
+    appId?: string;
+  }): Promise<SocialShareResult>;
+  /** 建群（交流群 = IM 群聊）并拉人 */
+  createGroup(input: { name: string; memberIds: string[] }): Promise<SocialCreateGroupResult>;
+}
+/** 按钮样式：`primary` 主行动，`danger` 拒绝类，缺省 `default` */
+export type AppInviteActionStyle = 'default' | 'primary' | 'danger';
+/** 动作声明的邀请终态 */
+export type AppInviteActionResponse = 'accept' | 'reject';
+/** 声明式动作：平台按此渲染按钮并通用执行（平台不解释动作语义） */
+export interface AppInviteAction {
+  /** 动作 id（APP 私有语义），回投信号 payload 里带回 */
+  id: string;
+  /** 按钮文案（发起方语言；平台不二次翻译） */
+  label: string;
+  /** 回投的事件动作名，平台自动补前缀成 `app.<appId>.<event>` */
+  event: string;
+  /** 声明「点击 = 邀请被接受 / 被拒绝」；缺省为纯动作，邀请保持 pending */
+  response?: AppInviteActionResponse;
+  /** 点击时先由平台打开该应用并带参数（snake_case = 线上落库格式） */
+  open?: {
+    app_id: string;
+    params?: Record<string, string>;
+  };
+  style?: AppInviteActionStyle;
+}
+/** 统一邀请通道入参（规范 §6.4） */
+export interface HostInviteSendInput {
+  /** 发起方 APP：卡片 `app_id` + 动作回投命名空间 `app.<appId>.<动作>` */
+  appId: string;
+  /** 对端用户 id（单聊会话按成员组合幂等创建/复用） */
+  peerUserId: string;
+  /** 邀请标识：同一邀请生命周期内不变（由 APP 生成，幂等与过期丢弃用） */
+  inviteId: string;
+  /** 卡片正文（人可读，必填） */
+  text: string;
+  /** 声明式动作：点击后回投 `app.<appId>.<action.event>` */
+  actions?: AppInviteAction[];
+  /** 过期时间戳（ms）；到时平台把卡片按钮置灰 */
+  expiresAt?: number;
+  /** 同时投递的在线即时信号（事件名自动拼 `app.<appId>.<signal.action>`） */
+  signal?: {
+    action: string;
+    payload?: Record<string, unknown>;
+  };
+}
+/** 邀请投递结果；`reason` 供界面提示，不抛错 */
+export interface HostInviteSendResult {
+  ok: boolean;
+  /** 承载本次邀请的单聊会话 id（成功时有值） */
+  conversationId?: string;
+  /** noIdentity=未登录；rejected=平台统一拒绝（准入 / 黑名单 / 应用不可用等） */
+  reason?: 'noIdentity' | 'rejected';
+}
+/** 统一邀请通道：一次调用 = 单聊会话 + 邀请卡片 + 可选实时信号 */
+export interface HostInvite {
+  send(input: HostInviteSendInput): Promise<HostInviteSendResult>;
+}

package/dist/types/zleap-sdk.d.ts

@@ -0,0 +1,232 @@
+/** @generated from packages/shared/src/apps/appSdk.ts; do not edit.
+ * Source SHA-256: a1b1201cc3f85268156163232b439d80e8621c9d543d70ed5008c158880ab8ce
+ * Rebuild with: node scripts/build-app-sdk.mjs
+ */
+/**
+ * @zleap/app-sdk 单文件源 —— 三形态统一 SDK（社交域方案 §6.1 / P4）。
+ *
+ * 三形态出口：
+ * - `connectZleapOs()`           iframe 形态：类型化包裹宿主注入的 `window.__ZLEAP_OS__`
+ * - `connectHostedApp(options)`  托管静态包：MessageChannel protocol 1 握手（kv / files）
+ * - `connectHostCapabilities()`  内置形态：适配 HostCapabilities（React Context 值直传）
+ *
+ * 自包含硬约束（勿破）：`scripts/build-app-sdk.mjs` 对本文件做类型擦除后断言产物无
+ * `import`，且 zleap-sdk.js / zleap-sdk.d.ts 要发给第三方独立使用 —— 故本文件**零运行时 import**。
+ * 社交 / 邀请等共享类型已拆至 appSdkTypes.ts（纯类型模块），此处以 `import type` 引用并
+ * re-export；类型擦除后产物依然零 import，约束不破。类型与 hostSocial.ts / appInvite.ts /
+ * hostCapabilities.tsx 保持**结构同形**（漂移由 appSdk.test.ts 的互赋值断言拦截）。
+ *
+ * 本地预校验（2026-09-17 Lzm，P0/P2/P5）：kv.set / kv.delete 的键格式与值大小在 SDK 侧
+ * 先行校验并抛出带中文说明的 42200，避免「请求打到后端被桥脱敏成 Invalid app request」。
+ * 预校验二轮（2026-09-18 Lzm）：expectedVersion 整数域 / 文件名安全规则 / KV 嵌套深度
+ * 上限与后端 app_runtime_validation 全口径对齐；canonicalJson 显式拒绝 toJSON 对象；
+ * connectZleapOs 对老版宿主缺失能力域给缺省拒绝实现（SDKError 40302，不再裸 TypeError）。
+ *
+ * 边界：SDK 只做协议封装与类型，不做权限判定（唯一裁决在后端 + 宿主桥 fail-closed）。
+ * 编码：utf8 | 语言：TypeScript | 作者：Lzm | 日期：2026-09-18
+ */
+import type { HostInvite, HostSocial } from './zleap-sdk-types';
+export type {
+  AppShareCardInput,
+  SocialPeer,
+  SocialConversation,
+  SocialFollowResult,
+  SocialShareResult,
+  SocialCreateGroupResult,
+  HostSocial,
+  AppInviteActionStyle,
+  AppInviteActionResponse,
+  AppInviteAction,
+  HostInviteSendInput,
+  HostInviteSendResult,
+  HostInvite,
+} from './zleap-sdk-types';
+export type NotifyLevel = 'info' | 'success' | 'warning' | 'error';
+/** 当前登录用户基本信息 */
+export interface ZleapUser {
+  id: string;
+  name: string;
+}
+export type HostedJSONValue =
+  | null
+  | boolean
+  | number
+  | string
+  | HostedJSONValue[]
+  | {
+      [key: string]: HostedJSONValue;
+    };
+export interface HostedKVEntry {
+  key: string;
+  value: HostedJSONValue;
+  version: number;
+  exists: boolean;
+}
+export interface HostedFile {
+  id: string;
+  name: string;
+  mime_type: string | null;
+  size: number;
+  version: number;
+}
+export interface HostedFilePage {
+  list: HostedFile[];
+  total: number;
+  page: number;
+  pageSize: number;
+}
+export interface HostedAppClient {
+  kv: {
+    get(args: { key: string }): Promise<HostedKVEntry>;
+    set(args: {
+      key: string;
+      value: HostedJSONValue;
+      expectedVersion: number;
+    }): Promise<HostedKVEntry>;
+    delete(args: { key: string; expectedVersion: number }): Promise<HostedKVEntry>;
+  };
+  files: {
+    list(args?: { page?: number; pageSize?: number }): Promise<HostedFilePage>;
+    read(args: { productionId: string }): Promise<{
+      file: HostedFile;
+      data: Uint8Array;
+    }>;
+    write(args: {
+      name: string;
+      data: ArrayBuffer | Uint8Array;
+      mimeType?: string;
+    }): Promise<HostedFile>;
+  };
+  close(): void;
+}
+/** Server business codes are preserved; request headers, tokens and stacks are never exposed. */
+export declare class SDKError extends Error {
+  readonly code: number;
+  constructor(message: string, code: number);
+}
+/** 错误码处置指引（2026-09-17 Lzm，P3） */
+export interface SDKErrorInfo {
+  code: number;
+  /** 是否可安全重试（幂等重试或重新读取后再试） */
+  retryable: boolean;
+  /** 人可读的处置建议（中文） */
+  hint: string;
+}
+/** describeError：SDKError.code → 结构化处置指引（2026-09-17 Lzm，P3；2026-09-18 补 40400）。40400=资源不存在；40900=连接关闭/请求ID重用；40901=KV 版本冲突（重读后重试） */
+export declare function describeError(code: number): SDKErrorInfo;
+/** Connect once from the app bootstrap. The child transfers a port; the host never posts data to '*'. */
+export declare function connectHostedApp(options?: {
+  timeoutMs?: number;
+}): Promise<HostedAppClient>;
+/** api.get 的查询参数（undefined 值被丢弃） */
+export type ApiQueryParams = Record<string, string | number | boolean | undefined>;
+/** 事件总线订阅回调：（载荷, 事件名） */
+export type OsEventHandler = (payload: unknown, event: string) => void;
+/**
+ * iframe 形态客户端：与宿主注入脚本 ZLEAP_OS_INJECT_SRC 的方法面逐一对齐。
+ * 能力未声明时调用被宿主桥 fail-closed 拒绝（reject），SDK 不做本地预判。
+ */
+export interface ZleapOsClient {
+  auth: {
+    getToken(): Promise<string | null>;
+    getUser(): Promise<ZleapUser | null>;
+    /** 查询本 APP 是否被授予某项能力（manifest.capabilities） */
+    hasPermission(capability: string): Promise<boolean>;
+  };
+  storage: {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+  };
+  notify: {
+    show(message: string, level?: NotifyLevel): Promise<void>;
+    /** 等待用户确认，无桥超时（用户可能长时间不点） */
+    confirm(title: string, content?: string): Promise<boolean>;
+  };
+  eventBus: {
+    emit(name: string, payload?: unknown): Promise<void>;
+    /** 订阅事件；返回 subscriptionId，供 off 退订 */
+    on(name: string, handler: OsEventHandler): Promise<string>;
+    off(subscriptionId: string): Promise<void>;
+  };
+  api: {
+    get<T = unknown>(path: string, params?: ApiQueryParams): Promise<T>;
+    post<T = unknown>(path: string, body?: unknown): Promise<T>;
+    put<T = unknown>(path: string, body?: unknown): Promise<T>;
+    del<T = unknown>(path: string): Promise<T>;
+  };
+  app: {
+    getManifest(): Promise<Record<string, unknown>>;
+    getAppId(): Promise<string>;
+  };
+  invite: HostInvite;
+  social: HostSocial;
+}
+/**
+ * iframe 形态入口：包裹宿主注入的 `window.__ZLEAP_OS__`（类型化 + 存在性校验）。
+ * 桥由 srcdoc 注入脚本同步建立，故本函数同步返回；缺桥即抛 SDKError(40301)。
+ */
+export declare function connectZleapOs(): ZleapOsClient;
+/**
+ * HostCapabilities 的 SDK 所需子集（结构同形，见 hostCapabilities.tsx）。
+ * 内置 APP 用法：`connectHostCapabilities(useHostCapabilities(), { appId: 'app-xxx' })`。
+ */
+export interface HostCapabilitiesSource {
+  confirm(options: { title: string; content?: string }): Promise<boolean>;
+  notify(level: NotifyLevel, title: string): void;
+  apiProxy<T = unknown>(
+    endpoint: string,
+    options?: {
+      method?: string;
+      body?: unknown;
+      headers?: Record<string, string>;
+    },
+  ): Promise<T>;
+  storage: {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+  };
+  auth: {
+    getToken(): string | null;
+    getUser(): ZleapUser | null;
+  };
+  invite?: HostInvite;
+  social?: HostSocial;
+}
+export interface ConnectHostCapabilitiesOptions {
+  /**
+   * 内置 APP 的 appId。通道 A 的宿主是全局单例、不带 per-app 身份，
+   * 故 appId 只能由调用方显式声明（内置 APP 静态已知自己的 id）。
+   */
+  appId?: string;
+}
+/**
+ * 内置形态客户端（与 ZleapOsClient 的差异 = 平台真实差异）：
+ * - 无 `auth.hasPermission`：通道 A 不带 per-app 身份，无法判定「本 APP」授权；
+ * - 无 `eventBus` / `app.getManifest`：HostCapabilities 未暴露；
+ * - `invite` / `social` 可选：宿主未提供时按不支持处理（字段缺省为 undefined）。
+ */
+export interface BuiltinClient {
+  auth: {
+    getToken(): Promise<string | null>;
+    getUser(): Promise<ZleapUser | null>;
+  };
+  storage: ZleapOsClient['storage'];
+  notify: ZleapOsClient['notify'];
+  api: ZleapOsClient['api'];
+  app: {
+    /** 来自 options.appId；未传时 reject SDKError(40302) */
+    getAppId(): Promise<string>;
+  };
+  invite?: HostInvite;
+  social?: HostSocial;
+}
+/**
+ * 内置形态入口：把 HostCapabilities 适配成与 iframe 形态尽量一致的异步面。
+ * 同步宿主方法（storage / auth / notify.show）统一包成 Promise，跨形态代码可复用。
+ */
+export declare function connectHostCapabilities(
+  host: HostCapabilitiesSource,
+  options?: ConnectHostCapabilitiesOptions,
+): BuiltinClient;

package/dist/workspace.js

@@ -0,0 +1,2 @@
+/*! @zleap-ai/app-sdk v0.10.0 | (c) 2026 Zleap | 专有许可，仅限在 zleapOS 应用中使用，见 LICENSE */
+var I=Object.defineProperty;var E=(i,t,o)=>t in i?I(i,t,{enumerable:!0,configurable:!0,writable:!0,value:o}):i[t]=o;var _=(i,t,o)=>E(i,typeof t!="symbol"?t+"":t,o);var a=class extends Error{constructor(o,u){super(o);_(this,"code");_(this,"operationId");this.name="WorkspaceError",this.code=o,this.operationId=u}};function y(){if(window.parent===window)return Promise.reject(new a("OPEN_IN_ZLEAP_OS"));let i=window.location.pathname.match(/^\/api\/v1\/app-packages\/runtime\/([A-Za-z0-9_-]{43})\//)?.[1];if(!i)return Promise.reject(new a("OPEN_IN_ZLEAP_OS"));let t=new MessageChannel,o=!1,u=!1,l=new Map;function w(){if(!o){o=!0;for(let e of l.values())clearTimeout(e.timer),e.reject(new a(e.operationId?"COMMIT_UNKNOWN":"CONNECTION_CLOSED",e.operationId));l.clear(),t.port1.postMessage({type:"__zleap_workspace_close"}),t.port1.close()}}window.addEventListener("pagehide",w,{once:!0});let m=new Promise((e,s)=>{let r=setTimeout(()=>{u||(u=!0,w(),s(new a("WORKSPACE_UNAVAILABLE")))},15e3);t.port1.onmessage=c=>{let n=c.data;if(!u&&n?.type==="__zleap_workspace_ready"&&n.protocol===1){u=!0,clearTimeout(r),e();return}if(typeof n?.requestId!="string")return;let p=l.get(n.requestId);p&&(l.delete(n.requestId),clearTimeout(p.timer),typeof n.error=="string"?p.reject(new a(n.error,p.operationId)):p.resolve(n.result))},t.port1.onmessageerror=()=>w(),t.port1.start(),window.parent.postMessage({type:"__zleap_workspace_connect",protocol:1,nonce:i},"*",[t.port2])});async function d(e,s={},r){if(await m,o)throw new a("CONNECTION_CLOSED",r);if(l.size>=4)throw new a("TOO_MANY_REQUESTS");return new Promise((c,n)=>{let p=crypto.randomUUID(),O=setTimeout(()=>{l.delete(p),n(new a(r?"COMMIT_UNKNOWN":"CALL_TIMEOUT",r))},e==="select"?18e4:3e4);l.set(p,{resolve:N=>c(N),reject:n,timer:O,operationId:r}),t.port1.postMessage({requestId:p,method:e,args:s})})}async function f(e,s,r=crypto.randomUUID()){let c=await d(e,{...s,operationId:r},r);if(c.status!=="succeeded")throw new a(c.status==="failed"?c.code??"MOVE_FAILED":"COMMIT_UNKNOWN",r);return c}return m.then(()=>({selectFolder:()=>d("select"),restoreFolder:()=>d("restore"),list:e=>d("list",{handle:e}),readImage:(e,s,r)=>d("image",{handle:e,fileId:s,expectedVersion:r}),createFolder:async(e,s,r)=>(await f("mkdir",{handle:e,name:s},r)).result,move:async(e,s,r,c)=>(await f("move",{source:e,destination:s,fileIds:r},c)).result,operation:e=>d("operation",{operationId:e}),createOperationId:()=>crypto.randomUUID(),close:w}))}export{a as WorkspaceError,y as connectWorkspace};

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@zleap-ai/app-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.10.0",
+  "description": "zleapOS 云开发前端 SDK：Cloud 数据库 / 文件 / 云函数（zl.cloud）、宿主能力（connectHostedApp）与工作区连接",
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zleap-ai/zleap-app-kit.git",
+    "directory": "packages/app-sdk"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./host": {
+      "types": "./dist/types/zleap-sdk.d.ts",
+      "import": "./dist/host.js",
+      "default": "./dist/host.js"
+    },
+    "./workspace": {
+      "types": "./dist/types/workspace.d.ts",
+      "import": "./dist/workspace.js",
+      "default": "./dist/workspace.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "keywords": [
+    "zleap",
+    "zleapos",
+    "app-cloud",
+    "sdk"
+  ]
+}