@xmaxai/sdk 1.0.1 → 1.0.3

package/CHANGELOG.md

@@ -9,16 +9,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- `client.files.uploadAndCheckImage(file)` — upload then Playground-style `/cos/image/check`, returns checked URL; existing `uploadImage` unchanged.
 - 双区域发布：同一套源码构建出 `@xmaxai/sdk`（国内，默认 `https://cloud.xmax.22duck.cn/open/api/v1`）与 `@xmaxai/sdk-global`（海外，默认 `https://api.xmax.cloud/open/api/v1`）。
 - 构建时区域开关 `XMAX_SDK_REGION`（`cn` | `global`），经 tsup 内联注入默认 `baseUrl`。
 - `XMAX_OPEN_API_BASE_URLS` 常量与 `XmaxSdkRegion` 类型。
 - `build:cn` / `build:global` / `publish:cn` / `publish:global` / `publish:all` 脚本及 `scripts/publish-sdk.mjs`。
+- `connect` 支持可选的 `onError` / `onDisconnect`（与 Decart Overview 对齐；不传则行为与原先一致）。
 
 ### Changed
 
 - `XMAX_OPEN_API_PRODUCTION_BASE_URL` 现按构建区域解析（默认 `cn`），不再硬编码单一地址。
+- **根入口正式对外**：`createXmaxClient` / `models` 等从 `@xmaxai/sdk`（或 `@xmaxai/sdk-global`）直接导入，不再标 `@deprecated`。
+- 移除 `@xmaxai/sdk/experimental` 子路径（发版前无外部依赖）；Realtime API 仅通过根入口导出。
+- 错误通过 `onError` 通知调用方处理。
 
-## [1.0.1 ] - 2026-07-01
+### Removed
+
+- Package export `./experimental` and `src/experimental` barrel.
+- Deprecated aliases and no-ops: `mirrorInput`, `setMode` / `RealtimeSetModeOptions`, `preserveLocalInput`, `getContentRect`, `RTC_PUBLISH_FPS`, `waitForRtcOutboundBeforeStart`, `waitForPublishedInputFramesBeforeStart`, React `changeModel`.
+
+## [1.0.3 ] - 2026-07-01
 
 ### Added
 
@@ -26,7 +36,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `XMAX_OPEN_API_PRODUCTION_BASE_URL` constant for explicit production API endpoint configuration.
 - `@xmaxai/sdk/experimental` subpath for `createXmaxClient`, drag, and related APIs.
 - Unit tests for RTC event builders, video size utilities, and HTTP client request handling.
-- Inline SVG icons for built-in error toasts (no host static assets required).
 
 ### Changed
 

package/README.md

@@ -28,8 +28,8 @@ npm install @xmaxai/sdk-global
 
 | 入口 | 说明 |
 |------|------|
-| `@xmaxai/sdk/experimental` | **推荐** — `createXmaxClient`、`models` |
-| `@xmaxai/sdk` | HTTP Client、`RtcManager`、房间事件等底层 API |
+| `@xmaxai/sdk` | **推荐** — `createXmaxClient`、`models`，以及 HTTP Client / RTC 底层 API |
+| `@xmaxai/sdk/react` | React bindings（可选） |
 
 ## 快速开始
 
@@ -38,7 +38,7 @@ npm install @xmaxai/sdk-global
 `baseUrl` 已内置生产环境默认值，一般无需传入；仅在 staging / 私有部署时覆盖。
 
 ```ts
-import { createXmaxClient, models } from "@xmaxai/sdk/experimental";
+import { createXmaxClient, models } from "@xmaxai/sdk";
 
 const model = models.realtime("x2.0");
 
@@ -78,13 +78,24 @@ await realtimeClient.stop();
 await realtimeClient.disconnect();
 ```
 
+### 上传参考图并健康检查（可选）
+
+与 Playground 加参考图相同：先 COS 上传，再 `POST /cos/image/check`。  
+现有 `client.files.uploadImage` **只上传、不做检查**；需要检查时：
+
+```ts
+const url = await client.files.uploadAndCheckImage(file);
+await realtimeClient.set({ image: url });
+```
+
 ### 流程说明
 
 - `createXmaxClient({ apiKey })` 即可，`baseUrl` 默认指向官方生产 Open API。
 - `connect()` 自动完成：createSession → heartbeat → join RTC → 推流 →（`autoStart: true` 时）发送 start。
 - `initialState.prompt` 传 `{ text: string }`；`initialState.image` 传参考图 URL。
 - 宿主自行提供 `#video-input` / `#video-output` 容器元素。
-- 未传 `onError` 时，API/RTC 错误会弹出内置 toast；传入 `onError` 则完全覆盖。
+- API/RTC 错误通过 `onError` 回调交给调用方处理。在 `createXmaxClient` 或 `connect` 任一处传入即可（`connect` 优先）。
+- `onDisconnect` 仅在 session 成功建立后断开时触发；`connect()` 失败不会回调。
 
 ### 自定义 baseUrl（可选）
 
@@ -92,7 +103,7 @@ await realtimeClient.disconnect();
 import {
   createXmaxClient,
   XMAX_OPEN_API_PRODUCTION_BASE_URL,
-} from "@xmaxai/sdk/experimental";
+} from "@xmaxai/sdk";
 
 const client = createXmaxClient({
   apiKey: "<YOUR_XMAX_API_KEY>",
@@ -124,6 +135,9 @@ client.realtime.connect(stream, {
   model: RealtimeModel,     // models.realtime("x2.0")
   localElement?: HTMLElement,
   remoteElement?: HTMLElement,
+  onRemoteStream?: (stream: MediaStream) => void,
+  onError?: (message, error?) => void,  // optional; overrides createXmaxClient.onError
+  onDisconnect?: (reason) => void,      // "client" | "session_inactive" | "heartbeat_error"
   mirror?: "auto" | boolean,
   initialState?: {
     prompt?: string | { text: string },