@heybox/hb-sdk-protocol 0.8.1-alpha.9 → 0.8.1

package/src/native-host.ts

@@ -0,0 +1,213 @@
+export {
+  MINI_PROGRAM_NATIVE_CHUNK_MAX_BYTES,
+  MINI_PROGRAM_NATIVE_HOST_CONTRACT_REVISION,
+  MINI_PROGRAM_NATIVE_HOST_DESCRIPTION,
+  MINI_PROGRAM_NATIVE_HOST_PROTOCOL_VERSION,
+  MINI_PROGRAM_NATIVE_OPERATIONS,
+} from './native-host-contract.generated';
+import { MINI_PROGRAM_NATIVE_CHUNK_MAX_BYTES } from './native-host-contract.generated';
+/** Android WebMessageListener object 与 iOS WKScriptMessageHandler 共用名称。 */
+export const MINI_PROGRAM_NATIVE_HOST_OBJECT = 'hbMiniProgramHost' as const;
+/** Native 通过主文档 CustomEvent 回送 progress/result/error。 */
+export const MINI_PROGRAM_NATIVE_HOST_MESSAGE_EVENT = 'heybox:miniprogram-native-host-message' as const;
+
+export type MiniProgramNativeHostDomain = 'system' | 'network' | 'files';
+
+/** H5 主文档发给 Native Host 的 operation 请求。 */
+export interface MiniProgramNativeHostRequest {
+  requestId: string;
+  domain: MiniProgramNativeHostDomain;
+  operation: string;
+  payload?: unknown;
+}
+
+/** 取消独立引用原请求，重复取消必须是幂等操作。 */
+export interface MiniProgramNativeHostCancel {
+  type: 'cancel';
+  requestId: string;
+}
+
+export interface MiniProgramNativeHostError {
+  code: string;
+  message: string;
+}
+
+export interface MiniProgramNativeHostDescription {
+  protocolVersion: number;
+  contractRevision: number;
+  operations: Readonly<Record<MiniProgramNativeHostDomain, readonly string[]>>;
+}
+
+export type MiniProgramNativeHostMessage =
+  | { requestId: string; type: 'progress'; payload: unknown }
+  | { requestId: string; type: 'result'; payload?: unknown }
+  | { requestId: string; type: 'error'; error: MiniProgramNativeHostError };
+
+export interface MiniProgramNativeBinaryChunk {
+  resourceId: string;
+  data: string;
+  byteLength: number;
+  eof: boolean;
+}
+
+export type MiniProgramNativeFileRef =
+  | { scope: 'sandbox'; kind: 'file' | 'directory'; relativePath: string }
+  | { scope: 'grant'; id: string; kind: 'file' | 'directory'; relativePath: string };
+
+export interface MiniProgramNativeFileDescriptor {
+  kind: 'file' | 'directory';
+  mode: 'read' | 'readwrite';
+  name: string;
+  ref: MiniProgramNativeFileRef;
+}
+
+export interface MiniProgramNativeNetworkOpenPayload {
+  purpose: 'request' | 'download';
+  url: string;
+  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
+  params?: Record<string, unknown>;
+  data?: unknown;
+  headers?: Record<string, string>;
+  bodyEncoding?: 'json' | 'form';
+  timeoutMs: number;
+}
+
+export interface MiniProgramNativeNetworkOpenResult {
+  status: number;
+  statusText?: string;
+  headers: Record<string, string[]>;
+  resourceId: string;
+}
+
+export interface MiniProgramNativeNetworkReadPayload {
+  resourceId: string;
+  maxBytes: number;
+}
+
+export interface MiniProgramNativeNetworkReleasePayload {
+  resourceId: string;
+}
+
+export interface MiniProgramNativeNetworkTransferPayload {
+  resourceId: string;
+  target: MiniProgramNativeFileRef;
+  mode: 'replace-existing' | 'create-exclusive' | 'upsert';
+  maxBytes?: number;
+  expectedBytes?: number;
+}
+
+export interface MiniProgramNativeNetworkTransferResult {
+  committedBytes: number;
+}
+
+export interface MiniProgramNativeFilesCreatePayload {
+  ref: MiniProgramNativeFileRef;
+  recursive: boolean;
+  exclusive: boolean;
+}
+
+export interface MiniProgramNativeFilesRemovePayload {
+  ref: MiniProgramNativeFileRef;
+  recursive?: boolean;
+}
+
+export interface MiniProgramNativeFilesRefPayload {
+  ref: MiniProgramNativeFileRef;
+}
+
+export interface MiniProgramNativeFilesOpenPayload extends MiniProgramNativeFilesRefPayload {
+  maxBytes: number;
+}
+
+export interface MiniProgramNativeFilesOpenResult {
+  resourceId: string;
+}
+
+/** openWrite 后按序发送；eof=true 的最后一块触发 atomic commit。 */
+export interface MiniProgramNativeFilesWritePayload extends MiniProgramNativeBinaryChunk {}
+
+export type MiniProgramNativeFilesStatResult =
+  | { kind: 'file'; size: number; modifiedAt?: number; createdAt?: number }
+  | { kind: 'directory'; modifiedAt?: number; createdAt?: number };
+
+export interface MiniProgramNativeFilesListPayload extends MiniProgramNativeFilesRefPayload {
+  limit: number;
+}
+
+export interface MiniProgramNativeFilesPickFilesPayload {
+  mode: 'read' | 'readwrite';
+  accept?: string[];
+  multiple: boolean;
+}
+
+export interface MiniProgramNativeFilesPickDirectoryPayload {
+  mode: 'read' | 'readwrite';
+}
+
+export interface MiniProgramNativeFilesSaveFilePayload {
+  suggestedName: string;
+}
+
+export interface MiniProgramNativeTransferProgress {
+  resourceId: string;
+  loaded: number;
+}
+
+export function isMiniProgramNativeHostMessage(value: unknown): value is MiniProgramNativeHostMessage {
+  if (!isRecord(value) || !isNonEmptyString(value.requestId)) return false;
+  if (value.type === 'progress') return Object.prototype.hasOwnProperty.call(value, 'payload');
+  if (value.type === 'result') return !Object.prototype.hasOwnProperty.call(value, 'error');
+  if (value.type !== 'error' || !isRecord(value.error)) return false;
+  return isNonEmptyString(value.error.code) && isNonEmptyString(value.error.message);
+}
+
+export function isMiniProgramNativeHostDescription(value: unknown): value is MiniProgramNativeHostDescription {
+  if (
+    !isRecord(value) ||
+    !isPositiveSafeInteger(value.protocolVersion) ||
+    !isPositiveSafeInteger(value.contractRevision) ||
+    !isRecord(value.operations)
+  )
+    return false;
+  const operations = value.operations;
+  if (
+    !isOperationList(operations.system) ||
+    !isOperationList(operations.network) ||
+    !isOperationList(operations.files)
+  )
+    return false;
+  return operations.system.includes('describe');
+}
+
+export function isMiniProgramNativeBinaryChunk(value: unknown): value is MiniProgramNativeBinaryChunk {
+  return (
+    isRecord(value) &&
+    isNonEmptyString(value.resourceId) &&
+    typeof value.data === 'string' &&
+    Number.isSafeInteger(value.byteLength) &&
+    Number(value.byteLength) >= 0 &&
+    Number(value.byteLength) <= MINI_PROGRAM_NATIVE_CHUNK_MAX_BYTES &&
+    typeof value.eof === 'boolean' &&
+    (Number(value.byteLength) > 0 || value.eof)
+  );
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isNonEmptyString(value: unknown): value is string {
+  return typeof value === 'string' && value.length > 0;
+}
+
+function isPositiveSafeInteger(value: unknown): value is number {
+  return Number.isSafeInteger(value) && Number(value) > 0;
+}
+
+function isOperationList(value: unknown): value is string[] {
+  return (
+    Array.isArray(value) &&
+    value.every(operation => isNonEmptyString(operation) && operation === operation.trim()) &&
+    new Set(value).size === value.length
+  );
+}

package/src/payloads.ts

@@ -494,6 +494,7 @@ export const COMPANION_ALIAS_PATTERN = /^[a-z][a-z0-9-]{0,31}$/;
 /** Companion Host 可跨 bridge 保留的稳定领域错误码。 */
 export const COMPANION_ERROR_CODES = [
   'COMPANION_UNSUPPORTED',
+  'COMPANION_PREVIEW_UNSUPPORTED',
   'COMPANION_NOT_DECLARED',
   'COMPANION_TARGET_UNSUPPORTED',
   'COMPANION_NOT_PREPARED',
@@ -527,7 +528,7 @@ export interface CompanionInfo {
   archiveBytes: number;
   signatureStatus: CompanionSignatureStatus;
   /** Host 确认的产物来源；旧 Host 缺省时来源未知。 */
-  source?: 'local-dev' | 'released';
+  source?: 'local-dev' | 'preview' | 'released';
 }
 
 export interface CompanionErrorSummary {

package/types/index.d.ts

@@ -2,6 +2,7 @@ export * from './bridge';
 export * from './capabilities';
 export * from './constants';
 export * from './guards';
+export * from './native-host';
 export * from './payloads';
 export * from './permission-catalog';
 export * from './permissions';

package/types/native-host-contract.generated.d.ts

@@ -0,0 +1,18 @@
+/** 由 scripts/generate-native-host-contract.mjs 生成，请勿手改。 */
+export declare const MINI_PROGRAM_NATIVE_HOST_PROTOCOL_VERSION: 1;
+export declare const MINI_PROGRAM_NATIVE_HOST_CONTRACT_REVISION: 1;
+export declare const MINI_PROGRAM_NATIVE_CHUNK_MAX_BYTES: 65536;
+export declare const MINI_PROGRAM_NATIVE_OPERATIONS: {
+    readonly system: readonly ["describe"];
+    readonly network: readonly ["open", "read", "release", "transfer"];
+    readonly files: readonly ["create", "remove", "exists", "openRead", "openWrite", "read", "release", "write", "stat", "list", "pickFiles", "pickDirectory", "saveFile"];
+};
+export declare const MINI_PROGRAM_NATIVE_HOST_DESCRIPTION: {
+    readonly protocolVersion: 1;
+    readonly contractRevision: 1;
+    readonly operations: {
+        readonly system: readonly ["describe"];
+        readonly network: readonly ["open", "read", "release", "transfer"];
+        readonly files: readonly ["create", "remove", "exists", "openRead", "openWrite", "read", "release", "write", "stat", "list", "pickFiles", "pickDirectory", "saveFile"];
+    };
+};

package/types/native-host.d.ts

@@ -0,0 +1,147 @@
+export { MINI_PROGRAM_NATIVE_CHUNK_MAX_BYTES, MINI_PROGRAM_NATIVE_HOST_CONTRACT_REVISION, MINI_PROGRAM_NATIVE_HOST_DESCRIPTION, MINI_PROGRAM_NATIVE_HOST_PROTOCOL_VERSION, MINI_PROGRAM_NATIVE_OPERATIONS, } from './native-host-contract.generated';
+/** Android WebMessageListener object 与 iOS WKScriptMessageHandler 共用名称。 */
+export declare const MINI_PROGRAM_NATIVE_HOST_OBJECT: "hbMiniProgramHost";
+/** Native 通过主文档 CustomEvent 回送 progress/result/error。 */
+export declare const MINI_PROGRAM_NATIVE_HOST_MESSAGE_EVENT: "heybox:miniprogram-native-host-message";
+export type MiniProgramNativeHostDomain = 'system' | 'network' | 'files';
+/** H5 主文档发给 Native Host 的 operation 请求。 */
+export interface MiniProgramNativeHostRequest {
+    requestId: string;
+    domain: MiniProgramNativeHostDomain;
+    operation: string;
+    payload?: unknown;
+}
+/** 取消独立引用原请求，重复取消必须是幂等操作。 */
+export interface MiniProgramNativeHostCancel {
+    type: 'cancel';
+    requestId: string;
+}
+export interface MiniProgramNativeHostError {
+    code: string;
+    message: string;
+}
+export interface MiniProgramNativeHostDescription {
+    protocolVersion: number;
+    contractRevision: number;
+    operations: Readonly<Record<MiniProgramNativeHostDomain, readonly string[]>>;
+}
+export type MiniProgramNativeHostMessage = {
+    requestId: string;
+    type: 'progress';
+    payload: unknown;
+} | {
+    requestId: string;
+    type: 'result';
+    payload?: unknown;
+} | {
+    requestId: string;
+    type: 'error';
+    error: MiniProgramNativeHostError;
+};
+export interface MiniProgramNativeBinaryChunk {
+    resourceId: string;
+    data: string;
+    byteLength: number;
+    eof: boolean;
+}
+export type MiniProgramNativeFileRef = {
+    scope: 'sandbox';
+    kind: 'file' | 'directory';
+    relativePath: string;
+} | {
+    scope: 'grant';
+    id: string;
+    kind: 'file' | 'directory';
+    relativePath: string;
+};
+export interface MiniProgramNativeFileDescriptor {
+    kind: 'file' | 'directory';
+    mode: 'read' | 'readwrite';
+    name: string;
+    ref: MiniProgramNativeFileRef;
+}
+export interface MiniProgramNativeNetworkOpenPayload {
+    purpose: 'request' | 'download';
+    url: string;
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
+    params?: Record<string, unknown>;
+    data?: unknown;
+    headers?: Record<string, string>;
+    bodyEncoding?: 'json' | 'form';
+    timeoutMs: number;
+}
+export interface MiniProgramNativeNetworkOpenResult {
+    status: number;
+    statusText?: string;
+    headers: Record<string, string[]>;
+    resourceId: string;
+}
+export interface MiniProgramNativeNetworkReadPayload {
+    resourceId: string;
+    maxBytes: number;
+}
+export interface MiniProgramNativeNetworkReleasePayload {
+    resourceId: string;
+}
+export interface MiniProgramNativeNetworkTransferPayload {
+    resourceId: string;
+    target: MiniProgramNativeFileRef;
+    mode: 'replace-existing' | 'create-exclusive' | 'upsert';
+    maxBytes?: number;
+    expectedBytes?: number;
+}
+export interface MiniProgramNativeNetworkTransferResult {
+    committedBytes: number;
+}
+export interface MiniProgramNativeFilesCreatePayload {
+    ref: MiniProgramNativeFileRef;
+    recursive: boolean;
+    exclusive: boolean;
+}
+export interface MiniProgramNativeFilesRemovePayload {
+    ref: MiniProgramNativeFileRef;
+    recursive?: boolean;
+}
+export interface MiniProgramNativeFilesRefPayload {
+    ref: MiniProgramNativeFileRef;
+}
+export interface MiniProgramNativeFilesOpenPayload extends MiniProgramNativeFilesRefPayload {
+    maxBytes: number;
+}
+export interface MiniProgramNativeFilesOpenResult {
+    resourceId: string;
+}
+/** openWrite 后按序发送；eof=true 的最后一块触发 atomic commit。 */
+export interface MiniProgramNativeFilesWritePayload extends MiniProgramNativeBinaryChunk {
+}
+export type MiniProgramNativeFilesStatResult = {
+    kind: 'file';
+    size: number;
+    modifiedAt?: number;
+    createdAt?: number;
+} | {
+    kind: 'directory';
+    modifiedAt?: number;
+    createdAt?: number;
+};
+export interface MiniProgramNativeFilesListPayload extends MiniProgramNativeFilesRefPayload {
+    limit: number;
+}
+export interface MiniProgramNativeFilesPickFilesPayload {
+    mode: 'read' | 'readwrite';
+    accept?: string[];
+    multiple: boolean;
+}
+export interface MiniProgramNativeFilesPickDirectoryPayload {
+    mode: 'read' | 'readwrite';
+}
+export interface MiniProgramNativeFilesSaveFilePayload {
+    suggestedName: string;
+}
+export interface MiniProgramNativeTransferProgress {
+    resourceId: string;
+    loaded: number;
+}
+export declare function isMiniProgramNativeHostMessage(value: unknown): value is MiniProgramNativeHostMessage;
+export declare function isMiniProgramNativeHostDescription(value: unknown): value is MiniProgramNativeHostDescription;
+export declare function isMiniProgramNativeBinaryChunk(value: unknown): value is MiniProgramNativeBinaryChunk;

package/types/payloads.d.ts

@@ -468,7 +468,7 @@ export type CompanionSignatureStatus = 'unsigned' | 'valid' | 'invalid' | 'unkno
 /** Companion alias 的跨构建、Runtime 与 Host 规范。 */
 export declare const COMPANION_ALIAS_PATTERN: RegExp;
 /** Companion Host 可跨 bridge 保留的稳定领域错误码。 */
-export declare const COMPANION_ERROR_CODES: readonly ["COMPANION_UNSUPPORTED", "COMPANION_NOT_DECLARED", "COMPANION_TARGET_UNSUPPORTED", "COMPANION_NOT_PREPARED", "COMPANION_PREPARATION_CANCELLED", "COMPANION_DOWNLOAD_FAILED", "COMPANION_DESCRIPTOR_UNAVAILABLE", "COMPANION_ARCHIVE_INVALID", "COMPANION_INTEGRITY_FAILED", "COMPANION_ENTRYPOINT_INVALID", "COMPANION_USER_CANCELLED", "COMPANION_ELEVATION_DENIED", "COMPANION_OS_BLOCKED", "COMPANION_LAUNCH_FAILED", "COMPANION_SESSION_VERSION_MISMATCH", "COMPANION_SESSION_OWNERSHIP_LOST", "COMPANION_SESSION_EXITED", "COMPANION_PIPE_CLOSED", "COMPANION_OUTPUT_LIMIT", "COMPANION_PROCESS_CRASHED", "COMPANION_ATTACHMENT_NOT_FOUND", "COMPANION_NOTIFICATION_UNAVAILABLE", "COMPANION_TERMINATE_FAILED"];
+export declare const COMPANION_ERROR_CODES: readonly ["COMPANION_UNSUPPORTED", "COMPANION_PREVIEW_UNSUPPORTED", "COMPANION_NOT_DECLARED", "COMPANION_TARGET_UNSUPPORTED", "COMPANION_NOT_PREPARED", "COMPANION_PREPARATION_CANCELLED", "COMPANION_DOWNLOAD_FAILED", "COMPANION_DESCRIPTOR_UNAVAILABLE", "COMPANION_ARCHIVE_INVALID", "COMPANION_INTEGRITY_FAILED", "COMPANION_ENTRYPOINT_INVALID", "COMPANION_USER_CANCELLED", "COMPANION_ELEVATION_DENIED", "COMPANION_OS_BLOCKED", "COMPANION_LAUNCH_FAILED", "COMPANION_SESSION_VERSION_MISMATCH", "COMPANION_SESSION_OWNERSHIP_LOST", "COMPANION_SESSION_EXITED", "COMPANION_PIPE_CLOSED", "COMPANION_OUTPUT_LIMIT", "COMPANION_PROCESS_CRASHED", "COMPANION_ATTACHMENT_NOT_FOUND", "COMPANION_NOTIFICATION_UNAVAILABLE", "COMPANION_TERMINATE_FAILED"];
 export type CompanionErrorCode = (typeof COMPANION_ERROR_CODES)[number];
 export interface CompanionInfo {
     alias: string;
@@ -478,7 +478,7 @@ export interface CompanionInfo {
     archiveBytes: number;
     signatureStatus: CompanionSignatureStatus;
     /** Host 确认的产物来源；旧 Host 缺省时来源未知。 */
-    source?: 'local-dev' | 'released';
+    source?: 'local-dev' | 'preview' | 'released';
 }
 export interface CompanionErrorSummary {
     code: CompanionErrorCode;