@zleap-ai/app-sdk 0.0.0-stage → 0.10.0

package/dist/types/index.d.ts

@@ -0,0 +1,369 @@
+import { authorize, checkUpdate, getIdentity, getUpdateManager } from './app.js';
+import { type FunctionInput, type JobResult } from './execution.js';
+import { type UploadInput, type UploadResult, type DownloadResult, type DeleteInput, type DeleteResult } from './files.js';
+import { CloudError, type Capabilities, type CloudMethod, type CloudPushEvent, type CloudTransport } from './protocol.js';
+export type { CapabilityInput, JobInput, JobResult, FunctionInput } from './execution.js';
+import { FieldOperation, type Condition } from './values.js';
+export { CloudError } from './protocol.js';
+export { AppError } from './app.js';
+export type { AuthResult, AuthScope, UpdateCheckResult, UpdateManager } from './app.js';
+export type { Capabilities, CloudTransport } from './protocol.js';
+export { boundedBinary, writesCloud } from './protocol.js';
+export interface Callbacks<T> {
+    success?: (result: T) => void;
+    fail?: (error: CloudError) => void;
+    complete?: (result: T | CloudError) => void;
+}
+export interface Meta {
+    requestId: string;
+    operationId?: string;
+    version?: string;
+}
+export interface ReadResult<T> {
+    data: T;
+    errMsg: string;
+    _meta: Meta;
+}
+export interface CountResult {
+    total: number;
+    errMsg: string;
+    _meta: Meta;
+}
+export interface WatchResult {
+    data: Document[];
+    cursor: string;
+    changed: boolean;
+    hasMore: boolean;
+    errMsg: string;
+    _meta: Meta;
+}
+export interface WriteResult {
+    _id?: string;
+    stats: {
+        created: number;
+        updated: number;
+        removed: number;
+    };
+    errMsg: string;
+    _meta: Meta;
+}
+export interface OperationResult {
+    operationId: string;
+    state: 'succeeded';
+    result: WriteResult;
+}
+export interface AgentOptions {
+    operationId?: string;
+    expectedVersion?: string;
+}
+export interface WriteOptions {
+    data: Record<string, unknown>;
+    agentos?: AgentOptions;
+}
+export interface RemoveOptions {
+    agentos?: AgentOptions;
+}
+export type Document = Record<string, unknown> & {
+    _id: string;
+    _openid: string;
+    _version: string;
+};
+type CallbackMode<T> = Callbacks<T> & ({
+    success: (result: T) => void;
+} | {
+    fail: (error: CloudError) => void;
+} | {
+    complete: (result: T | CloudError) => void;
+});
+/**
+ * 「用宿主决定的环境」哨兵。
+ *
+ * 环境（dev/prod）是「部署 + 用户」的关系，不是应用能判断的事实：应用既不知道这台机器
+ * 开放了哪个数据域，也不知道当前用户是不是本应用的发布者。所以不要写死 `'dev'`，
+ * 传这个哨兵，由宿主在建立会话时解析（与服务端 SDK 的 `DYNAMIC_CURRENT_ENV` 同义）。
+ *
+ * 宿主未识别哨兵时握手会被拒（`ENV_MISMATCH`）—— 宁可失败也不默默落到 dev，
+ * 否则应用会以爲在用真实数据域而其实在沙箱里。
+ */
+export declare const DYNAMIC_CURRENT_ENV = "DYNAMIC_CURRENT_ENV";
+interface Session {
+    ready(): Promise<Capabilities>;
+    request(method: CloudMethod, args: Record<string, unknown>): Promise<{
+        value: Record<string, unknown>;
+        requestId: string;
+    }>;
+    createId(): string;
+    /**
+     * Host-pushed change events for this session.  Present only when the host
+     * negotiated a transport that supports push; `watch` still works without it.
+     */
+    onEvent?(handler: (event: CloudPushEvent) => void): () => void;
+}
+declare class Query {
+    protected readonly session: Session;
+    protected readonly key: string;
+    private readonly query;
+    constructor(session: Session, key: string, query?: Record<string, unknown>);
+    private with;
+    where(value: Record<string, unknown> | Condition): Query;
+    orderBy(path: string, direction: 'asc' | 'desc'): Query;
+    limit(value: number): Query;
+    skip(value: number): Query;
+    field(projection: Record<string, boolean>): Query;
+    get(options: CallbackMode<ReadResult<Document[]>>): void;
+    get(options?: undefined): Promise<ReadResult<Document[]>>;
+    count(options: CallbackMode<CountResult>): void;
+    count(options?: undefined): Promise<CountResult>;
+    watch(options?: {
+        cursor?: string;
+        query?: Record<string, unknown>;
+        maxDocs?: number;
+    }): Promise<WatchResult>;
+    after(): never;
+    /**
+     * Subscribe to changes in this collection, pushed by the host.
+     *
+     * Apps cannot hold their own connection (the sandboxed iframe pins
+     * `connect-src` to `'none'`), so the host subscribes to the platform channel
+     * on their behalf and forwards each change here.  Prefer this over calling
+     * `watch()` on a timer: it is the difference between reacting in milliseconds
+     * and re-reading the collection every N seconds.
+     *
+     * The callback carries only the change coordinates — re-read what you need via
+     * `get`/`watch`, treating the event as a signal rather than the payload.
+     * Returns an unsubscribe function.  When the host did not negotiate push the
+     * handler is never called, so callers that also poll stay correct.
+     */
+    onChange(handler: (change: CloudPushEvent) => void): () => void;
+    update(): never;
+    remove(): never;
+}
+declare class DocumentReference {
+    private readonly session;
+    private readonly collection;
+    private readonly id;
+    private readonly throwOnNotFound;
+    constructor(session: Session, collection: string, id: string, throwOnNotFound: boolean);
+    get(options: CallbackMode<ReadResult<Document | null>>): void;
+    get(options?: undefined): Promise<ReadResult<Document | null>>;
+    private mutate;
+    set(options: WriteOptions & CallbackMode<WriteResult>): void;
+    set(options: WriteOptions): Promise<WriteResult>;
+    update(options: WriteOptions & CallbackMode<WriteResult>): void;
+    update(options: WriteOptions): Promise<WriteResult>;
+    remove(options: RemoveOptions & CallbackMode<WriteResult>): void;
+    remove(options?: RemoveOptions): Promise<WriteResult>;
+}
+declare class Collection extends Query {
+    private readonly throwOnNotFound;
+    constructor(session: Session, key: string, throwOnNotFound: boolean);
+    doc(id: string): DocumentReference;
+    add(options: WriteOptions & CallbackMode<WriteResult>): void;
+    add(options: WriteOptions): Promise<WriteResult>;
+}
+export declare function createCloudClient(factory?: (environmentKey: string) => CloudTransport): {
+    /** 应用运行期能力：版本更新（与云资源无关） */
+    app: {
+        getUpdateManager: typeof getUpdateManager;
+        checkUpdate: typeof checkUpdate;
+    };
+    /** 授权登录：系统授权框 + openid（与云资源无关） */
+    auth: {
+        authorize: typeof authorize;
+        getIdentity: typeof getIdentity;
+    };
+    cloud: {
+        DYNAMIC_CURRENT_ENV: string;
+        init(options: {
+            env: string | {
+                database: string;
+                functions: string;
+                storage: string;
+            };
+            traceUser?: boolean;
+        }): void;
+        database(options?: {
+            throwOnNotFound?: boolean;
+        }): {
+            command: Readonly<{
+                eq: (value: unknown) => Condition;
+                neq: (value: unknown) => Condition;
+                gt: (value: unknown) => Condition;
+                gte: (value: unknown) => Condition;
+                lt: (value: unknown) => Condition;
+                lte: (value: unknown) => Condition;
+                in: (value: unknown[]) => Condition;
+                nin: (value: unknown[]) => Condition;
+                exists: (value: boolean) => Condition;
+                and: (...values: (Condition | Record<string, unknown>)[]) => Condition;
+                or: (...values: (Condition | Record<string, unknown>)[]) => Condition;
+                inc: (value: number) => FieldOperation;
+                set: (value: unknown) => FieldOperation;
+                remove: () => FieldOperation;
+            }>;
+            collection: (key: string) => Collection;
+            serverDate: (options?: {
+                offset?: number;
+            }) => FieldOperation;
+            runTransaction: (options?: Callbacks<never>) => void | Promise<never>;
+        };
+        callFunction(options: FunctionInput & Callbacks<JobResult>): Promise<JobResult> | void;
+        uploadFile(options: UploadInput & Callbacks<UploadResult>): Promise<UploadResult> | void;
+        downloadFile(options: {
+            fileID: string;
+        } & Callbacks<DownloadResult>): Promise<DownloadResult> | void;
+        deleteFile(options: DeleteInput & Callbacks<DeleteResult>): Promise<DeleteResult> | void;
+        getTempFileURL: (options?: Callbacks<never>) => void | Promise<never>;
+        os: {
+            files: {
+                getOperation: (operationValue: string) => Promise<{
+                    operation_id: string;
+                    state: "pending" | "succeeded" | "cancelled";
+                    chunk_size?: number;
+                    received?: number[];
+                    file?: Record<string, unknown> | null;
+                }>;
+                cancel: (operationValue: string) => Promise<{
+                    operation_id: string;
+                    state: "pending" | "succeeded" | "cancelled";
+                    chunk_size?: number;
+                    received?: number[];
+                    file?: Record<string, unknown> | null;
+                }>;
+                stat: (fileID: string) => Promise<UploadResult>;
+            };
+            capabilities: {
+                invoke: (args: import("./execution.js").CapabilityInput) => Promise<JobResult>;
+            };
+            jobs: {
+                submit: (args: import("./execution.js").JobInput) => Promise<JobResult>;
+                get: (args: {
+                    jobId: string;
+                }) => Promise<JobResult>;
+                result: (args: {
+                    jobId: string;
+                }) => Promise<JobResult>;
+                wait: (args: import("./execution.js").JobWaitInput) => Promise<JobResult>;
+                cancel: (args: {
+                    jobId: string;
+                }) => Promise<{
+                    cancelRequested: boolean;
+                }>;
+            };
+            api: {
+                token: () => Promise<import("./api.js").ApiToken>;
+                fetch: (path: string, init?: RequestInit) => Promise<Response>;
+            };
+            ready: () => Promise<Capabilities>;
+            getCapabilities: () => Promise<Capabilities>;
+            close: () => void | undefined;
+            operations: {
+                createId: () => string;
+                get: (operationId: string) => Promise<OperationResult>;
+            };
+        };
+    };
+};
+export declare const zl: {
+    /** 应用运行期能力：版本更新（与云资源无关） */
+    app: {
+        getUpdateManager: typeof getUpdateManager;
+        checkUpdate: typeof checkUpdate;
+    };
+    /** 授权登录：系统授权框 + openid（与云资源无关） */
+    auth: {
+        authorize: typeof authorize;
+        getIdentity: typeof getIdentity;
+    };
+    cloud: {
+        DYNAMIC_CURRENT_ENV: string;
+        init(options: {
+            env: string | {
+                database: string;
+                functions: string;
+                storage: string;
+            };
+            traceUser?: boolean;
+        }): void;
+        database(options?: {
+            throwOnNotFound?: boolean;
+        }): {
+            command: Readonly<{
+                eq: (value: unknown) => Condition;
+                neq: (value: unknown) => Condition;
+                gt: (value: unknown) => Condition;
+                gte: (value: unknown) => Condition;
+                lt: (value: unknown) => Condition;
+                lte: (value: unknown) => Condition;
+                in: (value: unknown[]) => Condition;
+                nin: (value: unknown[]) => Condition;
+                exists: (value: boolean) => Condition;
+                and: (...values: (Condition | Record<string, unknown>)[]) => Condition;
+                or: (...values: (Condition | Record<string, unknown>)[]) => Condition;
+                inc: (value: number) => FieldOperation;
+                set: (value: unknown) => FieldOperation;
+                remove: () => FieldOperation;
+            }>;
+            collection: (key: string) => Collection;
+            serverDate: (options?: {
+                offset?: number;
+            }) => FieldOperation;
+            runTransaction: (options?: Callbacks<never>) => void | Promise<never>;
+        };
+        callFunction(options: FunctionInput & Callbacks<JobResult>): Promise<JobResult> | void;
+        uploadFile(options: UploadInput & Callbacks<UploadResult>): Promise<UploadResult> | void;
+        downloadFile(options: {
+            fileID: string;
+        } & Callbacks<DownloadResult>): Promise<DownloadResult> | void;
+        deleteFile(options: DeleteInput & Callbacks<DeleteResult>): Promise<DeleteResult> | void;
+        getTempFileURL: (options?: Callbacks<never>) => void | Promise<never>;
+        os: {
+            files: {
+                getOperation: (operationValue: string) => Promise<{
+                    operation_id: string;
+                    state: "pending" | "succeeded" | "cancelled";
+                    chunk_size?: number;
+                    received?: number[];
+                    file?: Record<string, unknown> | null;
+                }>;
+                cancel: (operationValue: string) => Promise<{
+                    operation_id: string;
+                    state: "pending" | "succeeded" | "cancelled";
+                    chunk_size?: number;
+                    received?: number[];
+                    file?: Record<string, unknown> | null;
+                }>;
+                stat: (fileID: string) => Promise<UploadResult>;
+            };
+            capabilities: {
+                invoke: (args: import("./execution.js").CapabilityInput) => Promise<JobResult>;
+            };
+            jobs: {
+                submit: (args: import("./execution.js").JobInput) => Promise<JobResult>;
+                get: (args: {
+                    jobId: string;
+                }) => Promise<JobResult>;
+                result: (args: {
+                    jobId: string;
+                }) => Promise<JobResult>;
+                wait: (args: import("./execution.js").JobWaitInput) => Promise<JobResult>;
+                cancel: (args: {
+                    jobId: string;
+                }) => Promise<{
+                    cancelRequested: boolean;
+                }>;
+            };
+            api: {
+                token: () => Promise<import("./api.js").ApiToken>;
+                fetch: (path: string, init?: RequestInit) => Promise<Response>;
+            };
+            ready: () => Promise<Capabilities>;
+            getCapabilities: () => Promise<Capabilities>;
+            close: () => void | undefined;
+            operations: {
+                createId: () => string;
+                get: (operationId: string) => Promise<OperationResult>;
+            };
+        };
+    };
+};

package/dist/types/protocol.d.ts

@@ -0,0 +1,84 @@
+export declare const CLOUD_PROTOCOL = 2;
+export declare const CLOUD_CONNECT = "__zleap_cloud_connect";
+export declare const CLOUD_READY = "__zleap_cloud_ready";
+export declare const CLOUD_CLOSE = "__zleap_cloud_close";
+export declare const CLOUD_CLOSED = "__zleap_cloud_closed";
+/**
+ * Host → app **push** frame.  Every other frame is a handshake or a reply keyed
+ * by a requestId the app sent, so this is a genuinely new direction.
+ *
+ * The app iframe is pinned to `connect-src 'none'`, so it cannot open its own
+ * long-lived connection.  The host (apps/main) subscribes to the platform
+ * realtime channel on the app's behalf and forwards changes over this frame.
+ * The payload goes through the same whitelist projection as replies, so future
+ * control-plane fields can never become iframe credentials.
+ */
+export declare const CLOUD_EVENT = "__zleap_cloud_event";
+/** 页面接口令牌走独立消息：只调 OS 接口的应用不声明 Cloud 能力，也没有 Cloud 会话。 */
+export declare const APP_API_TOKEN = "__zleap_api_token";
+export declare const REQUEST_ID: RegExp;
+export declare const OPERATION_ID: RegExp;
+export type CloudMethod = 'documents.query' | 'documents.snapshot' | 'documents.mutate' | 'operations.get' | 'execution.invoke' | 'execution.get' | 'execution.cancel' | FileMethod;
+export type FileMethod = 'files.begin' | 'files.chunk' | 'files.commit' | 'files.cancel' | 'files.operation' | 'files.stat' | 'files.read' | 'files.delete';
+export interface Capabilities {
+    protocol: {
+        major: 2;
+        minor: 0;
+    };
+    profiles: string[];
+    operators: string[];
+    limits: Record<string, number>;
+    serverTime: number;
+}
+export interface CloudRequest {
+    requestId: string;
+    method: CloudMethod;
+    args: Record<string, unknown>;
+}
+export interface CloudTransport {
+    ready(): Promise<Capabilities>;
+    request(method: CloudMethod, args: Record<string, unknown>, requestId: string): Promise<unknown>;
+    /**
+     * Register a handler for host-pushed change events.
+     *
+     * Returns an unsubscribe function.  Apps cannot hold their own connection (the
+     * iframe is pinned to `connect-src 'none'`), so the host subscribes on their
+     * behalf and forwards changes here — this replaces polling for callers that
+     * would otherwise re-read on a timer.
+     */
+    onEvent(handler: (event: CloudPushEvent) => void): () => void;
+    close(): void;
+}
+/** One host-pushed change.  Mirrors what `cloudPushProjection` allows through. */
+export interface CloudPushEvent {
+    event: string;
+    app_id?: string;
+    /** The app-facing collection name, as declared in the manifest. */
+    collection_key?: string;
+    /** Data-service internal id; kept for correlation, not for filtering. */
+    collection_id?: string;
+    document_key?: string;
+    change_seq?: string;
+    operation_id?: string;
+}
+export declare class CloudError extends Error {
+    readonly errCode: string;
+    readonly errMsg: string;
+    readonly requestId?: string;
+    readonly operationId?: string;
+    readonly retryable: boolean;
+    readonly jobId?: string;
+    readonly invocationId?: string;
+    constructor(code: string, requestId?: string, operationId?: string, job?: {
+        jobId: string;
+        invocationId: string;
+    });
+}
+export declare function plain(value: unknown): value is Record<string, unknown>;
+export declare function keysOnly(value: Record<string, unknown>, keys: readonly string[]): boolean;
+export declare function boundedJson(value: unknown, max?: number): boolean;
+export declare function parseCloudRequest(value: unknown): CloudRequest | null;
+export declare function boundedBinary(value: unknown): value is Record<string, unknown> & {
+    data: ArrayBuffer;
+};
+export declare function writesCloud(method: CloudMethod): boolean;

package/dist/types/transport.d.ts

@@ -0,0 +1,2 @@
+import { type CloudTransport } from './protocol.js';
+export declare function connectCloudFrame(environmentKey: string): CloudTransport;

package/dist/types/values.d.ts

@@ -0,0 +1,51 @@
+export type ValueTypes = Record<string, 'date'>;
+export type Filter = {
+    op: string;
+    field?: string;
+    value?: unknown;
+    value_type?: 'date';
+    filters?: Filter[];
+};
+export declare class Condition {
+    readonly filters: Filter[];
+    constructor(filters: Filter[]);
+    and(other: Condition): Condition;
+    or(other: Condition): Condition;
+}
+export declare class FieldOperation {
+    readonly op: 'inc' | 'set' | 'remove' | 'serverDate';
+    readonly value?: unknown;
+    readonly offset: number;
+    constructor(op: 'inc' | 'set' | 'remove' | 'serverDate', value?: unknown, offset?: number);
+}
+export declare const command: Readonly<{
+    eq: (value: unknown) => Condition;
+    neq: (value: unknown) => Condition;
+    gt: (value: unknown) => Condition;
+    gte: (value: unknown) => Condition;
+    lt: (value: unknown) => Condition;
+    lte: (value: unknown) => Condition;
+    in: (value: unknown[]) => Condition;
+    nin: (value: unknown[]) => Condition;
+    exists: (value: boolean) => Condition;
+    and: (...values: (Condition | Record<string, unknown>)[]) => Condition;
+    or: (...values: (Condition | Record<string, unknown>)[]) => Condition;
+    inc: (value: number) => FieldOperation;
+    set: (value: unknown) => FieldOperation;
+    remove: () => FieldOperation;
+}>;
+export declare function fieldPath(path: string, system?: boolean): void;
+export declare function filterOf(value: Condition | Record<string, unknown>, field?: string): Filter;
+export interface FieldCommand {
+    op: string;
+    path: string;
+    value?: unknown;
+    value_types?: ValueTypes;
+    offset?: number;
+}
+export declare function encodeMutation(input: Record<string, unknown>, mode: string): {
+    data: Record<string, unknown>;
+    value_types: ValueTypes;
+    field_operations: FieldCommand[];
+};
+export declare function decodeDates(input: unknown, types: Record<string, unknown>): unknown;

package/dist/types/workspace.d.ts

@@ -0,0 +1,51 @@
+/** @generated from packages/shared/src/apps/workspaceSdk.ts; source SHA256: 47ceb13ac6415f7b347fb2d8932f3613d0a515aa71748e46e08056aa5c9764f2 */
+/** Standalone SDK for explicitly selected OS directories. No JWT, URL or raw API bridge. */
+export interface WorkspaceFolder {
+    handle: string;
+    name: string;
+}
+export interface WorkspaceFile {
+    id: string;
+    name: string;
+    mime_type: string | null;
+    size: number;
+    version: number;
+    created_at: number;
+}
+export interface WorkspaceListing {
+    files: WorkspaceFile[];
+    folders: WorkspaceFolder[];
+}
+export interface WorkspaceImage {
+    fileId: string;
+    name: string;
+    mimeType: string;
+    size: number;
+    version: number;
+    blob: Blob;
+}
+export interface WorkspaceOperation {
+    operationId: string;
+    status: 'pending' | 'succeeded' | 'failed' | 'unknown';
+    result?: unknown;
+    code?: string | null;
+}
+export declare class WorkspaceError extends Error {
+    readonly code: string;
+    readonly operationId?: string;
+    constructor(code: string, operationId?: string);
+}
+export declare function connectWorkspace(): Promise<{
+    selectFolder: () => Promise<WorkspaceFolder>;
+    restoreFolder: () => Promise<WorkspaceFolder | null>;
+    list: (handle: string) => Promise<WorkspaceListing>;
+    readImage: (handle: string, fileId: string, expectedVersion: number) => Promise<WorkspaceImage>;
+    createFolder: (parent: string, name: string, operationId?: string) => Promise<WorkspaceFolder>;
+    move: (source: string, destination: string, fileIds: string[], operationId?: string) => Promise<{
+        moved: number;
+        fileIds: string[];
+    }>;
+    operation: (operationId: string) => Promise<WorkspaceOperation>;
+    createOperationId: () => `${string}-${string}-${string}-${string}-${string}`;
+    close: () => void;
+}>;