@xmaxai/sdk 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+All notable changes to `@xmaxai/sdk` will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- 双区域发布：同一套源码构建出 `@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`。
+
+### Changed
+
+- `XMAX_OPEN_API_PRODUCTION_BASE_URL` 现按构建区域解析（默认 `cn`），不再硬编码单一地址。
+
+## [0.1.0] - 2026-07-01
+
+### Added
+
+- Initial public release preparation: MIT license, semver, npm metadata.
+- `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
+
+- **`baseUrl` is optional** on `createXmaxClient` (defaults to `XMAX_OPEN_API_PRODUCTION_BASE_URL`). Required on `XmaxOpenClient`.
+- Default React model aligned to `x2.0` (matches provider implementation and platform demos).
+- README documents all three API surfaces: imperative, React, and experimental Realtime.
+
+### Deprecated
+
+- Importing `createXmaxClient`, `RealtimeSession`, and drag utilities from the main entry. Use `@xmaxai/sdk/experimental` instead.
+- `DEFAULT_BASE_URL` alias — use `XMAX_OPEN_API_PRODUCTION_BASE_URL`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 XMAX
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,201 @@
+# @xmaxai/sdk
+
+面向 Xmax Open Platform 的浏览器端 SDK。公开 API 以 **headless Realtime 客户端**（`createXmaxClient`）为主：负责 session 生命周期、火山 RTC 进房推流、远端渲染绑定，以及 start/stop 信令。
+
+本包以浏览器环境为主要运行场景（依赖 `fetch` / `AbortController` / `File` / DOM / `HTMLCanvasElement.captureStream`）。
+
+> SDK **不包含 UI**（参考图选择器、prompt 输入框、视频布局等由宿主应用自行实现）。
+
+## 安装
+
+本 SDK 按接入区域发布为两个包，**API 完全一致**，仅内置的默认接口地址不同：
+
+| 包名 | 区域 | 默认接口 |
+|------|------|----------|
+| `@xmaxai/sdk` | 国内 | `https://cloud.xmax.22duck.cn/open/api/v1` |
+| `@xmaxai/sdk-global` | 海外 | `https://api.xmax.cloud/open/api/v1` |
+
+```bash
+# 国内
+npm install @xmaxai/sdk
+# 海外
+npm install @xmaxai/sdk-global
+```
+
+> 两个包由同一套源码构建（构建时通过 `XMAX_SDK_REGION` 注入默认地址），无需维护两份代码。任意包都可通过 `baseUrl` 显式覆盖默认地址。
+
+## 包入口
+
+| 入口 | 说明 |
+|------|------|
+| `@xmaxai/sdk/experimental` | **推荐** — `createXmaxClient`、`models` |
+| `@xmaxai/sdk` | HTTP Client、`RtcManager`、房间事件等底层 API |
+
+## 快速开始
+
+与平台 Playground 相同的调用方式：获取摄像头 → `createXmaxClient` → `connect`，通过 `initialState` 传入 **prompt** 和 **参考图 URL**。
+
+`baseUrl` 已内置生产环境默认值，一般无需传入；仅在 staging / 私有部署时覆盖。
+
+```ts
+import { createXmaxClient, models } from "@xmaxai/sdk/experimental";
+
+const model = models.realtime("x2.0");
+
+const stream = await navigator.mediaDevices.getUserMedia({
+  video: {
+    frameRate: model.fps,
+    width: model.width,
+    height: model.height,
+  },
+});
+
+const client = createXmaxClient({
+  apiKey: "<YOUR_XMAX_API_KEY>",
+});
+
+const localElement = document.querySelector("#video-input") as HTMLElement;
+const remoteElement = document.querySelector("#video-output") as HTMLElement;
+
+const realtimeClient = await client.realtime.connect(stream, {
+  model,
+  localElement,
+  remoteElement,
+  mirror: "auto",
+  initialState: {
+    prompt: { text: "<YOUR_PROMPT>" },
+    image: "<YOUR_REF_IMAGE_URL>",
+    autoStart: true,
+  },
+});
+
+await realtimeClient.setPrompt("<YOUR_PROMPT>");
+
+await realtimeClient.setRefImage("<YOUR_REF_IMAGE_URL>");
+await realtimeClient.restart();
+
+await realtimeClient.stop();
+await realtimeClient.disconnect();
+```
+
+### 流程说明
+
+- `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` 则完全覆盖。
+
+### 自定义 baseUrl（可选）
+
+```ts
+import {
+  createXmaxClient,
+  XMAX_OPEN_API_PRODUCTION_BASE_URL,
+} from "@xmaxai/sdk/experimental";
+
+const client = createXmaxClient({
+  apiKey: "<YOUR_XMAX_API_KEY>",
+  baseUrl: XMAX_OPEN_API_PRODUCTION_BASE_URL, // 或自定义前缀，如 https://your-host/open/api/v1
+});
+```
+
+---
+
+## API 参考
+
+### createXmaxClient
+
+```ts
+createXmaxClient({
+  apiKey: string,           // 必填
+  baseUrl?: string,         // 可选，默认内置生产环境地址
+  authToken?: string,
+  heartbeatIntervalMs?: number,
+  onError?: (message, error?) => void,
+  onLog?: (entry) => void,
+})
+```
+
+### client.realtime.connect
+
+```ts
+client.realtime.connect(stream, {
+  model: RealtimeModel,     // models.realtime("x2.0")
+  localElement?: HTMLElement,
+  remoteElement?: HTMLElement,
+  mirror?: "auto" | boolean,
+  initialState?: {
+    prompt?: string | { text: string },
+    image?: string,
+    autoStart?: boolean,
+  },
+  size?: [number, number],
+  mobile?: boolean,
+})
+```
+
+When `remoteElement` is provided, drag is enabled by default after generation starts. Pass `drag: false` to disable.
+
+### RealtimeSession 主要方法
+
+| 方法 | 说明 |
+|------|------|
+| `setPrompt(prompt)` | 更新 prompt 并重新生成 |
+| `setRefImage(url \| File)` | 设置参考图 |
+| `restart(options?)` | 用当前 prompt / 参考图重新生成 |
+| `sendTracks(tracks)` | 发送拖拽轨迹（通常由内置 drag 自动调用） |
+| `stop()` | 停止当前生成 |
+| `disconnect()` | 断开 session 并离开 RTC |
+
+---
+
+## 安全建议
+
+- `apiKey` / `authToken` 属于敏感信息，避免写入前端日志。
+- 生产环境建议通过后端签发短期令牌或 API 代理，避免在浏览器暴露高权限密钥。
+- COS STS 临时密钥会在上传期间存在于浏览器内存，请确保 STS 权限最小化。
+
+## 依赖说明
+
+| 依赖 | 用途 |
+|------|------|
+| `@volcengine/rtc` | 火山引擎 Web RTC |
+| `cos-js-sdk-v5` | 腾讯云 COS 直传 |
+
+## 开发与构建
+
+```bash
+pnpm -C packages/open-sdk install
+pnpm -C packages/open-sdk test
+pnpm -C packages/open-sdk build          # 默认按国内(cn)地址构建
+pnpm -C packages/open-sdk typecheck
+```
+
+### 双区域构建 / 发布
+
+一套源码 → 两个 npm 包。区域通过环境变量 `XMAX_SDK_REGION`（`cn` | `global`）在构建时注入。
+
+```bash
+# 仅构建
+pnpm -C packages/open-sdk run build:cn        # → 国内默认地址
+pnpm -C packages/open-sdk run build:global    # → 海外默认地址
+
+# 发布（会自动切换包名 + 以对应区域重新构建测试）
+pnpm -C packages/open-sdk run publish:cn      # 发布 @xmaxai/sdk
+pnpm -C packages/open-sdk run publish:global  # 发布 @xmaxai/sdk-global
+pnpm -C packages/open-sdk run publish:all     # 两个都发
+
+# 透传 npm 参数，例如预演 / 打 tag
+node packages/open-sdk/scripts/publish-sdk.mjs global --dry-run
+```
+
+> `publish-sdk.mjs` 会临时改写 `package.json` 的 `name` 后调用 `npm publish`，发布结束（含失败）都会还原为默认名。`package.json` 中 `publishConfig.provenance` 需在带 OIDC 的 CI 环境才生效，本地发布如报 provenance 相关错误可临时关闭。
+
+## 变更记录
+
+见 [CHANGELOG.md](./CHANGELOG.md)。
+
+## License
+
+[MIT](./LICENSE)