@heybox/hb-sdk 0.5.18 → 0.6.0

package/skill/scripts/sync-references.mjs

@@ -237,7 +237,7 @@ hb-sdk remote allowlist list
 hb-sdk remote allowlist add <heybox-id...>
 hb-sdk remote allowlist remove <heybox-id...>
 hb-sdk remote allowlist set <heybox-id...>
-hb-sdk remote deploy --release-note <text> [--skip-build | --from-version <version>] [--auto-publish]
+hb-sdk remote deploy --release-note <text> [--from-version <version>] [--auto-publish]
 hb-sdk remote versions
 hb-sdk remote preview <version>
 hb-sdk remote release <version> [--yes]
@@ -397,7 +397,7 @@ ${cliRemoteEntityDeploySection}
 Agent rules:
 
 - Use \`hb-sdk remote deploy --release-note <text>\` for normal build, upload, and submit-audit flows.
-- Use \`hb-sdk remote deploy --from-version <version> --release-note <text>\` to reuse a remote history artifact. Do not combine \`--from-version\` with \`--skip-build\`.
+- Use \`hb-sdk remote deploy --from-version <version> --release-note <text>\` to reuse a remote history artifact.
 - Verify remote deploy guidance says current-entity mismatch fails before precheck/build/upload/submit and never auto-switches the developer entity.
 - Never recommend top-level \`hb-sdk deploy\`; it has been removed rather than retained as a compatibility alias.
 - After non-auto deploy succeeds, suggest \`hb-sdk remote versions\` and then \`hb-sdk remote release <version>\` after approval. Do not send the user to Open for manual publish when the CLI command exists.

package/skill/skill.json

@@ -1,11 +1,11 @@
 {
   "name": "hb-sdk",
-  "skillVersion": "0.5.17+skill.0ad061ac9da8",
+  "skillVersion": "0.6.0+skill.451f74e19672",
   "sdk": {
     "package": "@heybox/hb-sdk",
-    "version": "0.5.17",
-    "compatibility": "0.5.17"
+    "version": "0.6.0",
+    "compatibility": "0.6.0"
   },
   "source": "https://open.xiaoheihe.cn/agent-skills/hb-sdk",
-  "integrity": "sha256-0ad061ac9da821bfea0db71d30404999c1bd3eb5fcddfb0c22211bd9939db2ae"
+  "integrity": "sha256-451f74e19672cca0953ebb9d47d6f2632c9341ba2c4f9bcf4a861d5344285673"
 }

package/types/cli/auth/base-url.d.ts

@@ -0,0 +1,20 @@
+export interface HeyboxBaseUrlEnv extends NodeJS.ProcessEnv {
+    HB_SDK_API_BASE_URL?: string;
+    HB_SDK_ALLOW_UNSAFE_API_BASE_URL?: string;
+    HB_SDK_LOGIN_BASE_URL?: string;
+}
+export interface HeyboxBaseUrlResolveOptions {
+    env?: HeyboxBaseUrlEnv;
+}
+export interface HeyboxApiBaseUrlResolveOptions extends HeyboxBaseUrlResolveOptions {
+    allowUnsafeApiBaseUrl?: boolean;
+    apiBaseUrl?: string;
+}
+export interface HeyboxLoginBaseUrlResolveOptions extends HeyboxBaseUrlResolveOptions {
+    loginBaseUrl?: string;
+}
+export declare const HEYBOX_API_BASE_URL = "https://api.xiaoheihe.cn";
+export declare const HEYBOX_LOGIN_BASE_URL = "https://login.xiaoheihe.cn";
+export declare function resolveHeyboxApiBaseUrl(options?: HeyboxApiBaseUrlResolveOptions): string;
+export declare function resolveHeyboxLoginBaseUrl(options?: HeyboxLoginBaseUrlResolveOptions): string;
+export declare function normalizeHeyboxOriginUrl(value: string, label: string): string;

package/types/cli/config.d.ts

@@ -0,0 +1,11 @@
+import type { RylaiServiceTagConfig } from '@heybox/hb-types';
+export type HeyboxCliRequestConfig = RylaiServiceTagConfig;
+export declare function configureHeyboxCliRequestConfig(config: HeyboxCliRequestConfig): void;
+export declare function readHeyboxCliRequestConfig(): HeyboxCliRequestConfig;
+/**
+ * 当 tag 为非空字符串时，把它设为 CLI 全局 default_tag；为空时不改动现有配置，
+ * 避免清掉 env 预设阶段已注入的值。
+ */
+export declare function applyServiceTagIfNeeded(tag: unknown): void;
+export declare function resolveHeyboxRylaiServiceTag(pathWithQuery?: string, config?: RylaiServiceTagConfig): string | undefined;
+export declare function normalizeHeyboxRylaiServiceTagConfig(config: HeyboxCliRequestConfig): RylaiServiceTagConfig;

package/types/core/client.d.ts

@@ -34,6 +34,11 @@ export declare class MiniProgramBridgeClient implements MiniProgramRequester {
     private readonly pendingRequests;
     private readonly eventBus;
     private readonly handleMessage;
+    private readonly handlePopState;
+    private readonly handleHashChange;
+    private readonly handlePageShow;
+    private readonly handleSecurityPolicyViolation;
+    private unsubscribeHistoryChanges?;
     private started;
     private readySettled;
     private readyPromise;
@@ -58,6 +63,8 @@ export declare class MiniProgramBridgeClient implements MiniProgramRequester {
     private ensureStarted;
     private postHandshake;
     private onMessage;
+    private postLocationReport;
+    private postCSPViolation;
     private handleEvent;
     private handleResponse;
     private postMessage;

package/types/core/csp-violation.d.ts

@@ -0,0 +1,5 @@
+import type { SDKCSPViolationPayload } from '../protocol/types';
+type CSPViolationLike = Pick<SecurityPolicyViolationEvent, 'blockedURI' | 'disposition' | 'effectiveDirective' | 'violatedDirective'>;
+/** 将浏览器 CSP 事件转换为不包含原始 URL 敏感部分的 bridge 载荷。 */
+export declare function createCSPViolationPayload(event: CSPViolationLike, baseHref: string, sdkVersion: string, cryptoImplementation: Crypto): Promise<SDKCSPViolationPayload>;
+export {};

package/types/core/history-observer.d.ts

@@ -0,0 +1,4 @@
+type HistoryChangeListener = () => void;
+/** 共享同一个 History patch，并在最后一个订阅者退出时精确恢复原属性。 */
+export declare function subscribeHistoryChanges(history: History, listener: HistoryChangeListener): () => void;
+export {};

package/types/core/version.d.ts

@@ -0,0 +1,2 @@
+/** 构建时替换为当前发布包的实际版本。 */
+export declare const HB_SDK_VERSION: string;

package/types/index.d.ts

@@ -1,6 +1,4 @@
-export { createMiniProgramSDK, MiniProgramSDK } from './core/sdk';
 export { HbMiniProgramSDKError, HbMiniProgramNetworkError } from './core/errors';
-export type { MiniProgramSDKOptions } from './core/client';
 export { ready, on, off, auth, user, share, viewport, storage, network, ui, device, navigation, cloud } from './core/singleton';
 export type { MiniProgramEventHandler, MiniProgramEventName, MiniProgramEventPayloadMap, } from './protocol/types';
 export type { LoginPayload, LoginResult, MiniProgramAuthModule } from './modules/auth';

package/types/miniapp-manifest/schema.d.ts

@@ -1,6 +1,7 @@
 export declare const MINIAPP_TEMPLATE_VERSION = "0.0.0";
 export interface MiniappManifest {
     [key: string]: unknown;
+    sdkVersion: string;
     version: string;
 }
 export interface ParseMiniappManifestResult {
@@ -12,4 +13,8 @@ export declare function validateMiniappPackageVersionForBuild(version: string):
 export declare function validateMiniappManifestVersion(version: unknown, sourceLabel?: string): string;
 export declare function renderMiniappManifest(manifest: MiniappManifest): string;
 export declare function parseMiniappManifestJson(raw: string, sourceLabel?: string): ParseMiniappManifestResult;
-export declare function validateMiniappManifestForDeploy(manifest: MiniappManifest): string;
+export declare function validateMiniappManifestForDeploy(manifest: MiniappManifest): {
+    version: string;
+    sdkVersion: string;
+};
+export declare function validateSdkVersion(version: unknown, sourceLabel?: string): string;

package/types/miniapp-manifest/sdk-version-policy.d.ts

@@ -0,0 +1,9 @@
+export declare function resolveMinimumSdkVersion(options: {
+    cacheDir: string;
+    environment: string;
+    fetchMinimumSdkVersion: () => Promise<string>;
+    now?: number;
+}): Promise<string>;
+export declare function validateCurrentSdkVersion(currentSdkVersion: string, minimumSdkVersion: string, options: {
+    allowPrerelease: boolean;
+}): string;

package/types/miniapp-publish/index.d.ts

@@ -2,6 +2,7 @@ export declare const MINIAPP_UPLOAD_SCOPE = "activity";
 export declare const ACTIVITY_UPLOAD_KEY_MAX_LENGTH = 64;
 export declare const MINIAPP_UPLOAD_BATCH_SIZE = 50;
 export declare const MINIAPP_UPLOAD_TOTAL_SIZE_LIMIT_BYTES: number;
+export declare const PUBLIC_USER_MINIPROGRAM_SDK_CONFIG_API_PATH = "/user_miniprogram/public/sdk_config";
 export declare const USER_MINIPROGRAM_ACCESS_STATUS_API_PATH = "/mall/developer/user_miniprogram/access_status";
 export declare const DEVELOPER_ENTITY_LIST_API_PATH = "/mall/developer/entity/list";
 export declare const DEVELOPER_ENTITY_SWITCH_API_PATH = "/mall/developer/entity/switch";

package/types/protocol/constants.d.ts

@@ -6,3 +6,9 @@ export declare const MINI_PROGRAM_MESSAGE_VERSION: 1;
 export declare const MINI_PROGRAM_BRIDGE_NONCE_PARAM: "hb_mini_bridge_nonce";
 /** SDK 初始化时发给父容器的握手方法名。 */
 export declare const SDK_HANDSHAKE_METHOD: "sdk.handshake";
+/** Runtime 主动探测 SDK 当前文档地址的内部方法名。 */
+export declare const RUNTIME_LOCATION_PROBE_METHOD: "runtime.location.probe";
+/** SDK 向 Runtime 报告当前文档地址的内部方法名。 */
+export declare const SDK_LOCATION_REPORT_METHOD: "sdk.location.report";
+/** SDK 向 Runtime 报告 CSP 违规的内部方法名。 */
+export declare const SDK_CSP_VIOLATION_METHOD: "sdk.csp.violation";

package/types/protocol/types.d.ts

@@ -27,6 +27,51 @@ export interface MiniProgramBridgeError {
     /** 可选调试数据，不保证结构稳定。 */
     data?: unknown;
 }
+/** SDK 初始化握手载荷。 */
+export interface SDKHandshakePayload {
+    /** 当前文档地址。 */
+    href: string;
+    /** 当前浏览器 User-Agent。 */
+    userAgent: string;
+    /** SDK 构建时注入的实际版本。 */
+    sdkVersion: string;
+}
+/** Runtime 发起 URL 探测时的载荷。 */
+export interface RuntimeLocationProbePayload {
+    /** 当前探测的唯一标识。 */
+    probeId: string;
+    /** Runtime 发起探测的时间戳。 */
+    timestamp: number;
+}
+/** SDK 主动或被动报告 URL 的触发来源。 */
+export type SDKLocationReportTrigger = 'probe' | 'history' | 'popstate' | 'hashchange' | 'pageshow' | 'resume';
+/** SDK 向 Runtime 报告当前 URL 的载荷。 */
+export interface SDKLocationReportPayload {
+    /** 响应探测时回传；主动报告时省略。 */
+    probeId?: string;
+    /** 当前文档完整地址，由 Runtime 执行范围校验。 */
+    href: string;
+    /** SDK 构建时注入的实际版本。 */
+    sdkVersion: string;
+    /** 本次报告的触发来源。 */
+    trigger: SDKLocationReportTrigger;
+    /** SDK 生成报告的时间戳。 */
+    timestamp: number;
+}
+/** CSP 阻断资源的归一化类型。 */
+export type SDKCSPBlockedResourceType = 'url' | 'inline' | 'eval' | 'unknown';
+/** SDK 向 Runtime 报告 CSP 违规的脱敏载荷。 */
+export interface SDKCSPViolationPayload {
+    effectiveDirective: string;
+    violatedDirective: string;
+    disposition: string;
+    blockedResourceType: SDKCSPBlockedResourceType;
+    blockedOrigin?: string;
+    redactedPathname?: string;
+    sanitizedPathnameHash?: string;
+    sdkVersion: string;
+    timestamp: number;
+}
 /**
  * SDK 与沙盒之间统一的 postMessage 信封。
  *

package/types/protocol.d.ts

@@ -1,6 +1,6 @@
-export { MINI_PROGRAM_BRIDGE_NONCE_PARAM, MINI_PROGRAM_MESSAGE_NAMESPACE, MINI_PROGRAM_MESSAGE_VERSION, SDK_HANDSHAKE_METHOD, } from './protocol/constants';
+export { MINI_PROGRAM_BRIDGE_NONCE_PARAM, MINI_PROGRAM_MESSAGE_NAMESPACE, MINI_PROGRAM_MESSAGE_VERSION, RUNTIME_LOCATION_PROBE_METHOD, SDK_CSP_VIOLATION_METHOD, SDK_HANDSHAKE_METHOD, SDK_LOCATION_REPORT_METHOD, } from './protocol/constants';
 export { isMiniProgramBridgeMessage } from './protocol/guards';
-export type { MiniProgramBridgeError, MiniProgramBridgeMessage, MiniProgramBridgeMessageType, MiniProgramEventHandler, MiniProgramEventName, MiniProgramEventPayloadMap, } from './protocol/types';
+export type { MiniProgramBridgeError, MiniProgramBridgeMessage, MiniProgramBridgeMessageType, MiniProgramEventHandler, MiniProgramEventName, MiniProgramEventPayloadMap, RuntimeLocationProbePayload, SDKCSPBlockedResourceType, SDKCSPViolationPayload, SDKHandshakePayload, SDKLocationReportPayload, SDKLocationReportTrigger, } from './protocol/types';
 export { AUTH_LOGIN_METHOD, CLOUD_LEADERBOARD_DELETE_CURRENT_USER_ENTRY_METHOD, CLOUD_LEADERBOARD_GET_CURRENT_USER_ENTRY_METHOD, CLOUD_LEADERBOARD_GET_INFO_METHOD, CLOUD_LEADERBOARD_GET_LIST_METHOD, CLOUD_LEADERBOARD_SUBMIT_METHOD, DEVICE_SET_CLIPBOARD_METHOD, DEVICE_VIBRATE_METHOD, MINI_PROGRAM_PROTOCOL_CAPABILITIES, NAVIGATION_CLOSE_METHOD, NAVIGATION_OPEN_APP_PAGE_METHOD, NAVIGATION_RELOAD_METHOD, NETWORK_REQUEST_METHOD, SHARE_SCREENSHOT_METHOD, SHARE_SHOW_SHARE_MENU_METHOD, STORAGE_GET_STORAGE_METHOD, STORAGE_SET_STORAGE_METHOD, UI_HIDE_LOADING_METHOD, UI_SHOW_LOADING_METHOD, UI_SHOW_TOAST_METHOD, USER_GET_CURRENT_USER_DETAIL_METHOD, USER_GET_CURRENT_USER_PROFILE_METHOD, USER_GET_INFO_METHOD, USER_GET_PLATFORM_ACCOUNT_INFO_METHOD, USER_GET_PLATFORM_ACCOUNT_OVERVIEW_METHOD, USER_GET_STEAM_GAME_LIST_METHOD, VIEWPORT_GET_WINDOW_INFO_METHOD, VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD, } from './protocol/capabilities';
 export type { MiniProgramDeviceMethod, MiniProgramAuthMethod, MiniProgramBridgeMethod, MiniProgramCapabilityDefinition, MiniProgramCapabilityModule, MiniProgramCapabilityPayload, MiniProgramCapabilityPayloadMap, MiniProgramCapabilityResult, MiniProgramCapabilityResultMap, MiniProgramCapabilityRisk, MiniProgramCloudMethod, MiniProgramNavigationMethod, MiniProgramNetworkMethod, MiniProgramShareMethod, MiniProgramStorageMethod, MiniProgramUiMethod, MiniProgramUserMethod, MiniProgramViewportMethod, } from './protocol/capabilities';
 export type { LoginPayload, LoginResult } from './modules/auth';

package/types/vite/html-policy.d.ts

@@ -0,0 +1,4 @@
+export declare const PRODUCTION_CSP: string;
+export declare function enforceMiniappHtmlPolicy(html: string, options?: {
+    hmrWebSocketUrl?: string;
+}): string;

package/types/vite/index.d.ts

@@ -1,21 +1,41 @@
+import { enforceViteSdkVersion as defaultEnforceRemoteSdkVersion } from './sdk-version-gate';
 type MiniappManifestPlugin = {
     name: string;
-    apply: 'build';
     config: (config: MiniappManifestUserConfig) => MiniappManifestUserConfig | void;
     configResolved: (resolved: MiniappManifestResolvedConfig) => void;
-    writeBundle: (this: MiniappManifestPluginContext) => void;
+    buildStart: () => Promise<void>;
+    /** Rollup 在构建失败后仍会跑 closeBundle；用 buildEnd 记录真实错误，避免二次校验掩盖原因。 */
+    buildEnd: (error?: Error) => void;
+    transformIndexHtml: (html: string) => string;
+    closeBundle: (this: MiniappManifestPluginContext) => Promise<void>;
 };
+export interface MiniappManifestOptions {
+    /** 仅供平台测试和自托管 Remote Environment adapter 使用。 */
+    enforceSdkVersion?: typeof defaultEnforceRemoteSdkVersion;
+}
 interface MiniappManifestUserConfig {
     base?: string;
+    define?: Record<string, string>;
 }
 interface MiniappManifestPluginContext {
     warn: (message: string) => void;
 }
 interface MiniappManifestResolvedConfig {
     root: string;
+    command: 'build' | 'serve';
     build: {
         outDir: string;
     };
+    server: {
+        host?: string | boolean;
+        port?: number;
+        hmr?: boolean | {
+            clientPort?: number;
+            host?: string;
+            port?: number;
+            protocol?: 'ws' | 'wss';
+        };
+    };
 }
-export declare function miniappManifest(): MiniappManifestPlugin;
+export declare function miniappManifest(options?: MiniappManifestOptions): MiniappManifestPlugin;
 export {};

package/types/vite/runtime-gate.d.ts

@@ -0,0 +1,5 @@
+import { type DefaultTreeAdapterMap } from 'parse5';
+type HtmlDocument = DefaultTreeAdapterMap['document'];
+export declare function injectMiniappRuntimeGate(document: HtmlDocument): void;
+export declare function hasMiniappRuntimeGate(html: string): boolean;
+export {};

package/types/vite/sdk-version-gate.d.ts

@@ -0,0 +1,8 @@
+export declare function enforceViteSdkVersion(options: {
+    sdkVersion: string;
+    environment: string;
+    fetchImpl?: typeof fetch;
+    cacheDir?: string;
+    allowPrerelease: boolean;
+    serviceTag?: string;
+}): Promise<string>;