@wovoon/polaris 0.3.0

package/README.md

@@ -0,0 +1,30 @@
+# @wovoon/polaris
+
+wovoon 平台官方 SDK（协议 1）：身份（每作品稳定 playerId）、数据集合（云存档/排行榜/用户数据）、云函数调用、房间实时通道。
+
+```bash
+npm i @wovoon/polaris
+```
+
+```ts
+import { PolarisClient, parseData } from "@wovoon/polaris";
+
+const polaris = new PolarisClient();               // 平台运行时同源自动识别作品
+const session = await polaris.ready();             // { appId, playerId, loggedIn, ... }
+
+const scores = polaris.collection("scores");
+await scores.add({ score: 42 });
+const top = await scores.query({ orderBy: "score", order: "desc", limit: 10,
+                                 where: { score: { gte: 10 } } });
+
+await polaris.call("settle", { score: 99 });       // 云函数（服务端权威结算）
+
+const room = polaris.room("lobby");                // 房间实时通道
+room.onMessage(m => console.log(m.from, m.data));
+room.send({ text: "你好" });
+```
+
+零构建页面可直接用平台同源下发的全局版：`<script src="/api/cloud/sdk.js"></script>` → `WovoonCloud.*`。
+
+- 协议正典与完整能力说明见仓库 [PROTOCOL.md](https://gitea/wujiwanjie/wovoon-polaris-sdk) 与 [llms.txt](./llms.txt)
+- 本地开发与校验：`npx @wovoon/cli init / dev / validate`

package/dist/client.d.ts

@@ -0,0 +1,87 @@
+/**
+ * @wovoon/polaris 运行时客户端（协议 1）。
+ * 在作品内通过 <script> 引入平台下发的 /api/cloud/sdk.js（全局 WovoonCloud）即可使用，
+ * 本模块提供同一 API 的 TypeScript 实现，供构建型项目以模块方式引入。
+ */
+export interface PolarisRequestInit {
+    /** 覆盖 API 基址（本地模拟器/自建环境用），默认同源。 */
+    baseUrl?: string;
+}
+export declare class PolarisError extends Error {
+    readonly code: string;
+    constructor(message: string, code?: string);
+}
+export interface PolarisSessionView {
+    appId: string;
+    playerId: string;
+    loggedIn: boolean;
+    displayName?: string | null;
+    avatarUrl?: string | null;
+}
+export interface PolarisDocumentView {
+    id: string;
+    ownerPlayerId: string | null;
+    /** 文档内容（JSON 字符串，与平台下发版一致；用 parse() 得到对象）。 */
+    data: string;
+    seq: number;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface PolarisQueryOptions {
+    limit?: number;
+    orderBy?: string;
+    order?: "asc" | "desc";
+    ownerOnly?: boolean;
+    where?: import("./protocol.js").WovoonWhereClause;
+    /**
+     * join 嵌入连接（最多 2 个）：
+     * - 单值 `{"author": "users.authorId"}` —— 主文档 authorId 字段的值 = users 集合文档 id，嵌入拍平对象或 null；
+     * - 多值 `{"comments": ["comments", "postId"]}` —— comments 集合 postId 字段的值 = 主文档 id，嵌入数组（每侧最多 200 条）。
+     */
+    join?: import("./protocol.js").WovoonJoinClause;
+}
+declare function parseData<T = Record<string, unknown>>(raw: string): T;
+export declare class PolarisClient {
+    private readonly baseUrl;
+    private sessionPromise;
+    private target;
+    constructor(init?: PolarisRequestInit);
+    /** 指定作品目标：deploymentId（运行地址自动识别）或 appId。 */
+    configure(options: {
+        deploymentId?: string;
+        appId?: string;
+    }): this;
+    private request;
+    private detectTarget;
+    session(): Promise<PolarisSessionView>;
+    identity(): Promise<{
+        playerId: string;
+        loggedIn: boolean;
+        displayName: string | null | undefined;
+        avatarUrl: string | null | undefined;
+    }>;
+    /** 云函数（function 能力）：call("settle", {score: 99}) → Promise<函数返回值>。 */
+    call<T = unknown>(name: string, event?: Record<string, unknown>): Promise<T>;
+    /**
+     * 房间实时通道（room 能力）。浏览器同源 WebSocket；返回的句柄与平台下发 SDK 行为一致：
+     * send 广播、onMessage 收 {from, data}、onPresence 收 joined/join/leave、onClose 断开。
+     */
+    room(roomId: string): {
+        send: (data: unknown) => void;
+        leave: () => void;
+        onMessage: (callback: (payload: {
+            from: string;
+            data: unknown;
+        }) => void) => void;
+        onPresence: (callback: (frame: unknown) => void) => void;
+        onClose: (callback: (payload: unknown) => void) => void;
+    };
+    collection<T = Record<string, unknown>>(name: string): {
+        query: (options?: PolarisQueryOptions) => Promise<PolarisDocumentView[]>;
+        get: (id: string) => Promise<PolarisDocumentView>;
+        add: (data: T) => Promise<PolarisDocumentView>;
+        set: (id: string, data: T) => Promise<PolarisDocumentView>;
+        remove: (id: string) => Promise<unknown>;
+    };
+}
+export { parseData };

package/dist/client.js

@@ -0,0 +1,176 @@
+/**
+ * @wovoon/polaris 运行时客户端（协议 1）。
+ * 在作品内通过 <script> 引入平台下发的 /api/cloud/sdk.js（全局 WovoonCloud）即可使用，
+ * 本模块提供同一 API 的 TypeScript 实现，供构建型项目以模块方式引入。
+ */
+export class PolarisError extends Error {
+    constructor(message, code = "WOVOON_CLOUD_ERROR") {
+        super(message);
+        this.code = code;
+        this.name = "PolarisError";
+    }
+}
+function parseData(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+}
+export class PolarisClient {
+    constructor(init = {}) {
+        this.sessionPromise = null;
+        this.target = "";
+        this.baseUrl = (init.baseUrl ?? "").replace(/\/$/, "");
+    }
+    /** 指定作品目标：deploymentId（运行地址自动识别）或 appId。 */
+    configure(options) {
+        this.target = options.deploymentId ?? options.appId ?? this.target;
+        this.sessionPromise = null;
+        return this;
+    }
+    request(method, path, body) {
+        return fetch(this.baseUrl + path, {
+            method,
+            credentials: "include",
+            headers: body === undefined ? undefined : { "Content-Type": "application/json" },
+            body: body === undefined ? undefined : JSON.stringify(body),
+        }).then(async (response) => {
+            const payload = await response.json().catch(() => null);
+            if (!response.ok || (payload && payload.success === false)) {
+                throw new PolarisError((payload && payload.message) || `HTTP ${response.status}`, (payload && payload.code) || "WOVOON_CLOUD_ERROR");
+            }
+            return (payload && payload.data);
+        });
+    }
+    detectTarget() {
+        if (this.target)
+            return this.target;
+        const match = /\/api\/public\/static\/([0-9a-fA-F-]{36})/.exec(typeof location === "undefined" ? "" : location.pathname);
+        return match ? match[1] : "";
+    }
+    session() {
+        if (this.sessionPromise)
+            return this.sessionPromise;
+        const target = this.detectTarget();
+        if (!target) {
+            this.sessionPromise = Promise.reject(new PolarisError("未识别作品：请通过 wovoon 平台运行，或 configure({deploymentId})", "WOVOON_TARGET_MISSING"));
+            return this.sessionPromise;
+        }
+        this.sessionPromise = this.request("POST", "/api/cloud/session", {
+            deploymentId: target,
+            appId: target,
+        });
+        return this.sessionPromise;
+    }
+    identity() {
+        return this.session().then((data) => ({
+            playerId: data.playerId,
+            loggedIn: data.loggedIn,
+            displayName: data.displayName,
+            avatarUrl: data.avatarUrl,
+        }));
+    }
+    /** 云函数（function 能力）：call("settle", {score: 99}) → Promise<函数返回值>。 */
+    call(name, event) {
+        if (!name)
+            throw new PolarisError("call(name) 需要函数名", "WOVOON_ARGUMENT");
+        return this.session().then((data) => this.request("POST", `/api/cloud/${data.appId}/functions/${encodeURIComponent(name)}`, {
+            event: event ?? {},
+        }));
+    }
+    /**
+     * 房间实时通道（room 能力）。浏览器同源 WebSocket；返回的句柄与平台下发 SDK 行为一致：
+     * send 广播、onMessage 收 {from, data}、onPresence 收 joined/join/leave、onClose 断开。
+     */
+    room(roomId) {
+        if (!roomId)
+            throw new PolarisError("room(roomId) 需要房间号", "WOVOON_ARGUMENT");
+        const listeners = {
+            message: [], presence: [], close: [],
+        };
+        let socket = null;
+        let left = false;
+        const emit = (kind, payload) => {
+            for (const callback of listeners[kind]) {
+                try {
+                    callback(payload);
+                }
+                catch { /* 监听器异常不中断通道 */ }
+            }
+        };
+        this.session().then((data) => {
+            if (left || typeof WebSocket === "undefined") {
+                if (!left)
+                    emit("close", { error: "当前环境不支持 WebSocket" });
+                return;
+            }
+            const origin = this.baseUrl || `${location.protocol}//${location.host}`;
+            const scheme = origin.startsWith("https") ? "wss" : "ws";
+            socket = new WebSocket(`${scheme}://${origin.replace(/^https?:\/\//, "")}/api/cloud/rooms/${data.appId}/${encodeURIComponent(roomId)}`);
+            socket.onmessage = (event) => {
+                let frame = null;
+                try {
+                    frame = JSON.parse(String(event.data));
+                }
+                catch {
+                    return;
+                }
+                if (!frame || !("type" in frame))
+                    return;
+                if (frame.type === "msg")
+                    emit("message", { from: frame.from, data: frame.data });
+                else if (frame.type === "joined" || frame.type === "join" || frame.type === "leave")
+                    emit("presence", frame);
+                else if (frame.type === "error")
+                    emit("message", { error: frame.message });
+            };
+            socket.onclose = () => emit("close", {});
+            socket.onerror = () => emit("close", {});
+        }).catch((error) => emit("close", { error: error.message }));
+        return {
+            send: (data) => {
+                if (socket && socket.readyState === 1)
+                    socket.send(JSON.stringify({ type: "msg", data }));
+            },
+            leave: () => {
+                left = true;
+                try {
+                    socket?.close();
+                }
+                catch { /* 已关闭 */ }
+            },
+            onMessage: (callback) => { listeners.message.push(callback); },
+            onPresence: (callback) => { listeners.presence.push(callback); },
+            onClose: (callback) => { listeners.close.push(callback); },
+        };
+    }
+    collection(name) {
+        if (!name)
+            throw new PolarisError("collection(name) 需要集合名", "WOVOON_ARGUMENT");
+        const ready = this.session().then((data) => data.appId);
+        const docUrl = (id) => ready.then((appId) => `/api/cloud/${appId}/collections/${encodeURIComponent(name)}/docs${id ? "/" + id : ""}`);
+        const client = this;
+        return {
+            query: (options = {}) => {
+                const params = [`limit=${options.limit ?? 20}`];
+                if (options.orderBy)
+                    params.push(`orderBy=${encodeURIComponent(options.orderBy)}`);
+                params.push(`order=${options.order === "asc" ? "asc" : "desc"}`);
+                if (options.ownerOnly)
+                    params.push("ownerOnly=true");
+                if (options.where)
+                    params.push(`where=${encodeURIComponent(JSON.stringify(options.where))}`);
+                if (options.join)
+                    params.push(`join=${encodeURIComponent(JSON.stringify(options.join))}`);
+                return docUrl().then((url) => client.request("GET", `${url}?${params.join("&")}`));
+            },
+            get: (id) => docUrl(id).then((url) => client.request("GET", url)),
+            add: (data) => docUrl().then((url) => client.request("POST", url, { data: JSON.stringify(data ?? {}) })),
+            set: (id, data) => docUrl(id).then((url) => client.request("PUT", url, { data: JSON.stringify(data ?? {}) })),
+            remove: (id) => docUrl(id).then((url) => client.request("DELETE", url)),
+        };
+    }
+}
+export { parseData };

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @wovoon/polaris SDK 入口（v0.1 协议层）。
+ * 当前导出协议 1 的冻结类型与常量；运行时客户端（identity/collection 等）在 M1 第 2~3 步落地。
+ */
+export { WOVOON_PROTOCOL_VERSION, COLLECTION_NAME_PATTERN, isValidCollectionName, CAPABILITY_PATTERN, isValidCapability, WovoonProtocolError, } from "./protocol.js";
+export { PolarisClient, PolarisError, parseData } from "./client.js";
+export type { WovoonCapability, WovoonCollectionName, WovoonManifest, WovoonSession, WovoonDocument, WovoonQueryOptions, WovoonFunctionEvent, WovoonFunctionResult, WovoonRoomFrame, } from "./protocol.js";
+export type { PolarisRequestInit, PolarisSessionView, PolarisDocumentView, PolarisQueryOptions } from "./client.js";

package/dist/index.js

@@ -0,0 +1,6 @@
+/**
+ * @wovoon/polaris SDK 入口（v0.1 协议层）。
+ * 当前导出协议 1 的冻结类型与常量；运行时客户端（identity/collection 等）在 M1 第 2~3 步落地。
+ */
+export { WOVOON_PROTOCOL_VERSION, COLLECTION_NAME_PATTERN, isValidCollectionName, CAPABILITY_PATTERN, isValidCapability, WovoonProtocolError, } from "./protocol.js";
+export { PolarisClient, PolarisError, parseData } from "./client.js";

package/dist/protocol.d.ts

@@ -0,0 +1,95 @@
+/**
+ * wovoon 平台协议 v1 类型定义（与 PROTOCOL.md 逐字对应）。
+ * 这些类型是冻结的公共 API：只加不改不删。任何 AI coding 工具以本文件为准确理解协议。
+ */
+/** 协议版本。协议 1 是当前唯一支持的版本。 */
+export declare const WOVOON_PROTOCOL_VERSION: 1;
+/** 协议 1 冻结的能力名。集合能力形如 `collection:${WovoonCollectionName}`。 */
+export type WovoonCapability = "identity" | `collection:${WovoonCollectionName}` | "function" | "room";
+/** 集合名：2-32 位，小写字母开头，仅小写字母/数字/下划线。运行时校验用下方正则。 */
+export type WovoonCollectionName = string;
+export declare const COLLECTION_NAME_PATTERN: RegExp;
+export declare function isValidCollectionName(name: string): name is WovoonCollectionName;
+/** manifest 里单个能力名的完整合法形态（与平台 AssetSecurityScanner.parseContract 的校验一致）。 */
+export declare const CAPABILITY_PATTERN: RegExp;
+export declare function isValidCapability(value: string): boolean;
+/** `.wovoon` 清单文件内容。空文件等价于 `{ protocol: 1 }`。 */
+export interface WovoonManifest {
+    /** 协议版本，当前仅支持 1，缺省为 1。 */
+    protocol?: typeof WOVOON_PROTOCOL_VERSION;
+    /** 声明使用的能力；未声明的能力在对应服务上线后不可调用。 */
+    capabilities?: WovoonCapability[];
+}
+/** 云函数事件与返回（function 能力）：任意 JSON 值；沙箱限时 3s/限内存 64MB，出入参 ≤32KB。 */
+export type WovoonFunctionEvent = Record<string, unknown>;
+export type WovoonFunctionResult = unknown;
+/** 房间帧（room 能力）：msg=消息、joined/join/leave=在线状态。 */
+export type WovoonRoomFrame = {
+    type: "joined";
+    roomId: string;
+    you: string;
+    players: string[];
+} | {
+    type: "join" | "leave";
+    playerId: string;
+} | {
+    type: "msg";
+    from: string;
+    data: unknown;
+} | {
+    type: "error";
+    message: string;
+};
+/** 运行会话身份（identity 能力）。playerId 对“账号×作品”稳定，跨作品不可关联。 */
+export interface WovoonSession {
+    appId: string;
+    playerId: string;
+    loggedIn: boolean;
+    displayName?: string | null;
+    avatarUrl?: string | null;
+}
+/** 集合中的文档视图（collection 能力）。ownerPlayerId 为作品内玩家 ID，不暴露平台账号。 */
+export interface WovoonDocument {
+    id: string;
+    ownerPlayerId: string | null;
+    data: Record<string, unknown>;
+    seq: number;
+    createdAt: string;
+    updatedAt: string;
+}
+/** where 条件：字段等值，或 {gte,lte,gt,lt,ne,in} 范围（数值/字符串比较）。 */
+export interface WovoonWhereClause {
+    [field: string]: unknown | {
+        gte?: number;
+        lte?: number;
+        gt?: number;
+        lt?: number;
+        ne?: unknown;
+        in?: unknown[];
+    };
+}
+/**
+ * join 嵌入连接声明（查询最多 2 个）：
+ * - 单值：`"集合.字段"` —— 主文档该字段的值 = 目标集合文档 id，结果嵌入拍平对象或 null；
+ * - 多值：`["集合", "字段"]` —— 目标集合该字段的值 = 主文档 id，结果嵌入数组（每侧最多 200 条）。
+ * 被连接集合必须同样在 .wovoon manifest 的 capabilities 中声明；嵌入按目标集合读规则逐文档过滤。
+ */
+export type WovoonJoinValue = string | [collection: string, on: string];
+export interface WovoonJoinClause {
+    [alias: string]: WovoonJoinValue;
+}
+/** 集合查询参数。orderBy 按文档字段数值排序（排行榜场景）。 */
+export interface WovoonQueryOptions {
+    limit?: number;
+    orderBy?: string;
+    order?: "asc" | "desc";
+    ownerOnly?: boolean;
+    afterSeq?: number;
+    where?: WovoonWhereClause;
+    join?: WovoonJoinClause;
+}
+/** 平台协议类错误：message 必含“缺什么 + 怎么修”。 */
+export declare class WovoonProtocolError extends Error {
+    readonly code: string;
+    constructor(message: string, code?: string);
+}

package/dist/protocol.js

@@ -0,0 +1,23 @@
+/**
+ * wovoon 平台协议 v1 类型定义（与 PROTOCOL.md 逐字对应）。
+ * 这些类型是冻结的公共 API：只加不改不删。任何 AI coding 工具以本文件为准确理解协议。
+ */
+/** 协议版本。协议 1 是当前唯一支持的版本。 */
+export const WOVOON_PROTOCOL_VERSION = 1;
+export const COLLECTION_NAME_PATTERN = /^[a-z][a-z0-9_]{1,31}$/;
+export function isValidCollectionName(name) {
+    return COLLECTION_NAME_PATTERN.test(name);
+}
+/** manifest 里单个能力名的完整合法形态（与平台 AssetSecurityScanner.parseContract 的校验一致）。 */
+export const CAPABILITY_PATTERN = /^(identity|function|room|collection:[a-z][a-z0-9_]{1,31})$/;
+export function isValidCapability(value) {
+    return CAPABILITY_PATTERN.test(value);
+}
+/** 平台协议类错误：message 必含“缺什么 + 怎么修”。 */
+export class WovoonProtocolError extends Error {
+    constructor(message, code = "WOVOON_PROTOCOL") {
+        super(message);
+        this.code = code;
+        this.name = "WovoonProtocolError";
+    }
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@wovoon/polaris",
+  "version": "0.3.0",
+  "description": "wovoon Polaris SDK——wovoon 大后台云能力客户端（身份/数据集合/云函数/房间实时），协议 1",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "PROTOCOL.md",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "tsc --noEmit"
+  },
+  "keywords": [
+    "wovoon",
+    "polaris",
+    "sdk",
+    "cloud",
+    "baas",
+    "game"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^26.5.1",
+    "typescript": "^7.0.2"
+  },
+  "repository": {
+    "type": "git"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}