@tapicker/bridge 1.0.0 → 1.1.0

package/README.md

@@ -1,6 +1,6 @@
 # Tapicker Bridge
 
-Tapicker Bridge connects external tools and AI agents to a Tapicker browser Extension. Use it to run and control Workflows, access extracted data, or receive Workflow status updates through the CLI, HTTP, or MCP.
+Tapicker Bridge connects external tools and AI agents to a Tapicker browser Extension. Use it to read Workflow guides and schemas, validate nodes, create and update Workflows, run and control Workflows, access extracted data, or receive Workflow status updates through the CLI, HTTP, or MCP.
 
 The Bridge routes commands; browser automation runs in the connected Tapicker Extension.
 
@@ -8,8 +8,15 @@ The Bridge routes commands; browser automation runs in the connected Tapicker Ex
 
 **Requirements:** Node.js 22 or later and the Tapicker Extension installed in a supported browser.
 
+Install the CLI globally:
+
 ```bash
 npm install --global @tapicker/bridge
+```
+
+Start Bridge in the foreground:
+
+```bash
 tapicker bridge start
 ```
 
@@ -21,23 +28,16 @@ Copy a Workflow ID in Tapicker and run it:
 tapicker workflow start <workflowId> --watch
 ```
 
-Bridge listens on `127.0.0.1` by default and tries ports `9520`–`9530`. If it selects a port other than `9520`, pass the actual port with `--port` to CLI commands.
+Bridge listens on `127.0.0.1` by default and tries ports `9520`–`9530`. If it selects a port other than `9520`, pass the actual address with `--url http://127.0.0.1:<port>` to business CLI commands, or set `TAPICKER_BRIDGE_URL`.
 
-## Learn the User Flows
+## Documentation
 
+- [Overview](https://www.tapicker.com/docs/bridge-overview) — understand how Bridge connects external tools to Tapicker.
 - [Getting Started](https://www.tapicker.com/docs/bridge-getting-started) — install Bridge, pair an Extension, and run your first Workflow.
-- [Control Workflows](https://www.tapicker.com/docs/bridge-workflows) — start, pause, resume, stop, and watch Workflows.
-- [Connect an AI Agent](https://www.tapicker.com/docs/bridge-ai-agents) — use MCP or the HTTP API.
-- [Remote Deployment](https://www.tapicker.com/docs/bridge-remote-deployment) — configure TLS and a Bearer Token.
-- [API Reference](https://www.tapicker.com/docs/bridge-reference) — CLI commands, HTTP endpoints, MCP tools, and status events.
-
-## Documentation in This Package
-
-- [CLI reference](docs/cli.md)
-- [HTTP API reference](docs/http-api.md)
-- [MCP setup and tools](docs/mcp.md)
-- [Pairing, configuration, and security](docs/operations.md)
-- [Workflow status WebSocket](docs/workflow-watch.md)
+- [CLI Commands](https://www.tapicker.com/docs/bridge-cli-commands) — manage Bridge and use Workflow/data commands.
+- [HTTP API](https://www.tapicker.com/docs/bridge-http-api) — call the API and subscribe to status events.
+- [MCP Integration](https://www.tapicker.com/docs/bridge-mcp-integration) — configure an agent and author Workflows.
+- [Remote Deployment](https://www.tapicker.com/docs/bridge-remote-deployment) — configure TLS, authentication, and remote clients.
 
 ## Security
 

package/dist/bridge/bridge-service.d.ts

@@ -27,7 +27,7 @@ export declare class BridgeService extends EventEmitter {
     initialize(): Promise<void>;
     attachExtension(socket: WebSocket, remoteAddress?: string): ExtensionSession;
     sendCommand<T>(type: string, data: unknown, clientId?: string): Promise<T>;
-    sendCommandWithClientId<T>(type: string, data: unknown, clientId?: string): Promise<{
+    sendCommandWithClientId<T>(type: string, data: unknown, clientId?: string, timeout?: number): Promise<{
         clientId: string;
         result: Awaited<T>;
     }>;

package/dist/bridge/bridge-service.js

@@ -49,10 +49,10 @@ export class BridgeService extends EventEmitter {
         });
         session.on('message', (message) => {
             const status = session.getStatus();
-            if (status.ready && status.clientId && message.type === 'workflow.status') {
+            if (status.ready && status.clientId && message.type === 'workflow.status.changed') {
                 const parsed = WorkflowStatusDataSchema.safeParse(message.data);
                 if (parsed.success) {
-                    this.emit('workflow.status', {
+                    this.emit('workflow.status.changed', {
                         clientId: status.clientId,
                         ...parsed.data,
                     });
@@ -76,7 +76,7 @@ export class BridgeService extends EventEmitter {
         const session = this.selectCommandSession(type, clientId);
         return session.request(type, data);
     }
-    async sendCommandWithClientId(type, data, clientId) {
+    async sendCommandWithClientId(type, data, clientId, timeout) {
         const session = this.selectCommandSession(type, clientId);
         const selectedClientId = session.getStatus().clientId;
         if (!selectedClientId) {
@@ -84,7 +84,7 @@ export class BridgeService extends EventEmitter {
         }
         return {
             clientId: selectedClientId,
-            result: await session.request(type, data),
+            result: await session.request(type, data, timeout),
         };
     }
     assertExtensionCapability(type, clientId) {
@@ -100,13 +100,13 @@ export class BridgeService extends EventEmitter {
     selectCommandSession(type, clientId) {
         const readySessions = [...this.sessionsByClientId.entries()].filter(([, session]) => {
             const status = session.getStatus();
-            return status.connected && status.ready;
+            return session.isConnected() && status.ready;
         });
         let session;
         if (clientId) {
             session = this.sessionsByClientId.get(clientId);
             const status = session?.getStatus();
-            if (!status?.connected || !status.ready) {
+            if (!session?.isConnected() || !status?.ready) {
                 throw new BridgeError('ExtensionNotConnected', `Tapicker Extension ${clientId} is not connected`, {
                     status: 409,
                     details: { clientId },
@@ -144,8 +144,8 @@ export class BridgeService extends EventEmitter {
     }
     getExtensionStatuses() {
         return [...this.sessions]
+            .filter((session) => session.isConnected())
             .map((session) => session.getStatus())
-            .filter((status) => status.connected)
             .sort((left, right) => (left.clientName || '').localeCompare(right.clientName || ''));
     }
     getPairingCode() {

package/dist/bridge/control.js

@@ -135,7 +135,7 @@ function handleControlSocket(socket, handle) {
             sendControlError(socket, new BridgeError('InvalidBridgeControlRequest', 'Unsupported Bridge control action', { status: 400 }));
             return;
         }
-        void handle(action)
+        handle(action)
             .then((data) => socket.end(`${JSON.stringify({ ok: true, data })}\n`))
             .catch((error) => sendControlError(socket, error));
     });

package/dist/bridge/export-store.d.ts

@@ -0,0 +1,35 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { DataExportResult } from '../protocol/schema.js';
+/**
+ * 暂存文件并在导出确认后发布；回执与文件一起保留至过期。
+ */
+export declare class ExportStore {
+    private readonly directory;
+    private readonly pending;
+    private readonly downloads;
+    constructor(directory: string);
+    create(generate: (upload: {
+        exportId: string;
+        uploadToken: string;
+        maxBytes: number;
+    }) => Promise<Omit<DataExportResult, 'fileSize' | 'downloadPath' | 'expiresAt'>>): Promise<{
+        tableId: string;
+        tableName: string;
+        clientId: string;
+        format: "xlsx" | "xls" | "csv" | "json" | "xml" | "txt";
+        filename: string;
+        rowCount: number;
+        byteSize: number;
+        fileSize: string;
+        downloadPath: string;
+        expiresAt: string;
+    }>;
+    upload(exportId: string, request: IncomingMessage): Promise<void>;
+    download(exportId: string, response: ServerResponse): Promise<void>;
+    cleanup(): Promise<void>;
+    private usedBytes;
+    private listIds;
+    private fileStat;
+    private readReceipt;
+}
+//# sourceMappingURL=export-store.d.ts.map

package/dist/bridge/export-store.js

@@ -0,0 +1,195 @@
+import { randomUUID } from 'node:crypto';
+import { createWriteStream } from 'node:fs';
+import { mkdir, open, readdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { Transform } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { BridgeError } from '../errors.js';
+import { DataExportResultSchema } from '../protocol/schema.js';
+const EXPORT_TTL = 24 * 60 * 60_000;
+const UPLOAD_TTL = 30 * 60_000;
+const MAX_FILE_BYTES = 128 * 1024 * 1024;
+const MAX_TOTAL_BYTES = 2 * 1024 * 1024 * 1024;
+const EXPORT_ID = /^[0-9a-f]{8}-(?:[0-9a-f]{4}-){3}[0-9a-f]{12}$/;
+const StoredExportReceiptSchema = DataExportResultSchema.partial({ fileSize: true });
+/**
+ * 暂存文件并在导出确认后发布；回执与文件一起保留至过期。
+ */
+export class ExportStore {
+    directory;
+    pending = new Map();
+    downloads = new Map();
+    constructor(directory) {
+        this.directory = directory;
+    }
+    async create(generate) {
+        await mkdir(this.directory, { recursive: true, mode: 0o700 });
+        await this.cleanup();
+        const exportId = randomUUID();
+        const pending = { token: randomUUID() };
+        this.pending.set(exportId, pending);
+        const dir = join(this.directory, exportId);
+        try {
+            // 每个在途导出预留单文件上限，避免多个上传同时超过总容量。
+            const reserved = new Set(this.pending.keys());
+            if ((await this.usedBytes(reserved)) + reserved.size * MAX_FILE_BYTES > MAX_TOTAL_BYTES) {
+                throw new BridgeError('ExportStorageFull', 'The export directory is full. Try again after exports expire.', {
+                    status: 507,
+                });
+            }
+            await mkdir(dir, { mode: 0o700 });
+            const receipt = await generate({ exportId, uploadToken: pending.token, maxBytes: MAX_FILE_BYTES });
+            if (this.pending.get(exportId)?.bytes !== receipt.byteSize) {
+                throw new BridgeError('InvalidExtensionResponse', 'The export file was not uploaded completely', {
+                    status: 502,
+                });
+            }
+            const result = DataExportResultSchema.parse({
+                ...receipt,
+                fileSize: formatExportFileSize(receipt.byteSize),
+                downloadPath: `/v1/exports/${exportId}`,
+                expiresAt: new Date(Date.now() + EXPORT_TTL).toISOString(),
+            });
+            await rename(join(dir, 'file.part'), join(dir, 'file'));
+            await writeFile(join(dir, 'receipt.part'), JSON.stringify(result), { mode: 0o600 });
+            await rename(join(dir, 'receipt.part'), join(dir, 'receipt.json'));
+            return result;
+        }
+        finally {
+            this.pending.delete(exportId);
+            // 上传失败或进程中断留下的文件统一按过期时间回收。
+        }
+    }
+    async upload(exportId, request) {
+        const pending = this.pending.get(exportId);
+        if (!pending || request.headers.authorization !== `Bearer ${pending.token}`) {
+            throw new BridgeError('Unauthorized', 'Invalid export upload credentials', { status: 401 });
+        }
+        if (pending.isUploading || pending.bytes !== undefined) {
+            throw new BridgeError('ExportAlreadyUploaded', 'This export already has an upload', { status: 409 });
+        }
+        pending.isUploading = true;
+        let bytes = 0;
+        let oversized = false;
+        const limiter = new Transform({
+            transform(chunk, _encoding, callback) {
+                bytes += chunk.length;
+                if (bytes > MAX_FILE_BYTES) {
+                    oversized = true;
+                    callback(new BridgeError('ExportTooLarge', 'The export file exceeds the size limit', { status: 413 }));
+                }
+                else
+                    callback(null, chunk);
+            },
+        });
+        if (Number(request.headers['content-length']) > MAX_FILE_BYTES) {
+            request.resume();
+            throw new BridgeError('ExportTooLarge', 'The export file exceeds the size limit', { status: 413 });
+        }
+        try {
+            // 单独传输文件字节，避免整个请求进入内存。
+            await pipeline(request, limiter, createWriteStream(join(this.directory, exportId, 'file.part'), {
+                flags: 'wx',
+                mode: 0o600,
+            }));
+            pending.bytes = bytes;
+        }
+        catch (error) {
+            if (oversized)
+                throw new BridgeError('ExportTooLarge', 'The export file exceeds the size limit', { status: 413 });
+            throw error;
+        }
+    }
+    async download(exportId, response) {
+        const dir = join(this.directory, exportId);
+        const receipt = await this.readReceipt(dir);
+        if (!receipt || Date.parse(receipt.expiresAt) <= Date.now()) {
+            throw new BridgeError('ExportNotFound', 'The export is unavailable or has expired', { status: 404 });
+        }
+        this.downloads.set(exportId, (this.downloads.get(exportId) ?? 0) + 1);
+        try {
+            const file = await open(join(dir, 'file'), 'r').catch((error) => {
+                if (error.code === 'ENOENT')
+                    throw new BridgeError('ExportNotFound', 'The export is unavailable', { status: 404 });
+                throw error;
+            });
+            const filename = encodeURIComponent(Buffer.from(receipt.filename).toString('utf8')).replace(/['()*]/g, (char) => '%' + char.charCodeAt(0).toString(16).toUpperCase());
+            response.setHeader('Content-Type', 'application/octet-stream');
+            response.setHeader('Content-Length', receipt.byteSize);
+            response.setHeader('Content-Disposition', `attachment; filename*=UTF-8''${filename}`);
+            response.setHeader('Cache-Control', 'no-store');
+            await pipeline(file.createReadStream(), response);
+        }
+        finally {
+            const count = this.downloads.get(exportId) ?? 1;
+            if (count > 1)
+                this.downloads.set(exportId, count - 1);
+            else
+                this.downloads.delete(exportId);
+        }
+    }
+    async cleanup() {
+        for (const id of await this.listIds()) {
+            if (this.pending.has(id) || this.downloads.has(id))
+                continue;
+            const dir = join(this.directory, id);
+            const receipt = await this.readReceipt(dir);
+            const expiresAt = receipt ? Date.parse(receipt.expiresAt) : (await this.fileStat(dir))?.mtimeMs;
+            if (expiresAt !== undefined && (receipt ? expiresAt : expiresAt + UPLOAD_TTL) <= Date.now()) {
+                await rm(dir, { recursive: true, force: true });
+            }
+        }
+    }
+    async usedBytes(reserved) {
+        let bytes = 0;
+        for (const id of await this.listIds()) {
+            if (reserved.has(id))
+                continue;
+            const dir = join(this.directory, id);
+            bytes +=
+                (await this.fileStat(join(dir, 'file')))?.size ?? (await this.fileStat(join(dir, 'file.part')))?.size ?? 0;
+        }
+        return bytes;
+    }
+    async listIds() {
+        const entries = await readdir(this.directory, { withFileTypes: true }).catch((error) => {
+            if (error.code === 'ENOENT')
+                return [];
+            throw error;
+        });
+        return entries.filter((entry) => entry.isDirectory() && EXPORT_ID.test(entry.name)).map((entry) => entry.name);
+    }
+    async fileStat(path) {
+        return stat(path).catch((error) => {
+            if (error.code === 'ENOENT')
+                return undefined;
+            throw error;
+        });
+    }
+    async readReceipt(dir) {
+        const raw = await readFile(join(dir, 'receipt.json'), 'utf8').catch((error) => {
+            if (error.code === 'ENOENT')
+                return undefined;
+            throw error;
+        });
+        if (raw === undefined)
+            return undefined;
+        try {
+            const result = StoredExportReceiptSchema.safeParse(JSON.parse(raw));
+            return result.success ? result.data : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+}
+function formatExportFileSize(bytes) {
+    if (bytes < 1024)
+        return `${bytes}B`;
+    if (bytes < 1024 ** 2)
+        return `${Number((bytes / 1024).toFixed(1))}K`;
+    if (bytes < 1024 ** 3)
+        return `${Number((bytes / 1024 ** 2).toFixed(1))}M`;
+    return `${Number((bytes / 1024 ** 3).toFixed(1))}G`;
+}
+//# sourceMappingURL=export-store.js.map

package/dist/bridge/extension-session.d.ts

@@ -1,12 +1,13 @@
 import { EventEmitter } from 'node:events';
 import type { WebSocket } from 'ws';
-import type { ExtensionPairInput } from '../protocol/schema.js';
+import type { ExtensionHelloInput, ExtensionPairInput } from '../protocol/schema.js';
 export type ExtensionSessionStatus = {
-    connected: boolean;
     ready: boolean;
     pairingRequired?: boolean;
     clientId?: string;
     clientName?: string;
+    clientVersion?: string;
+    user?: ExtensionHelloInput['user'];
     capabilities: string[];
 };
 export type ExtensionSessionOptions = {
@@ -24,10 +25,16 @@ export declare class ExtensionSession extends EventEmitter {
     private pairingRequired;
     private clientId;
     private clientName;
+    private clientVersion;
+    private user;
     private capabilities;
     private pendingRequests;
     constructor(socket: WebSocket, options: ExtensionSessionOptions);
     start(): void;
+    /**
+     * 判断底层连接是否仍可用，供会话筛选和命令发送使用。
+     */
+    isConnected(): boolean;
     getStatus(): ExtensionSessionStatus;
     request<T>(type: string, data: unknown, timeout?: number): Promise<T>;
     close(code?: number, reason?: string): void;

package/dist/bridge/extension-session.js

@@ -1,7 +1,9 @@
+import { z } from 'zod';
 import { EventEmitter } from 'node:events';
 import { DEFAULT_REQUEST_TIMEOUT } from '../constants.js';
 import { BridgeError, safeError, safeSuccess } from '../errors.js';
 import { BridgeHelloDataSchema, BridgePairDataSchema, ExtensionHelloInputSchema, ExtensionPairInputSchema, SafeResultSchema, createEnvelope, parseEnvelope, } from '../protocol/schema.js';
+const UpstreamErrorDetailsSchema = z.looseObject({ upstreamStatus: z.number().int().min(400).max(599) });
 export class ExtensionSession extends EventEmitter {
     socket;
     options;
@@ -9,6 +11,8 @@ export class ExtensionSession extends EventEmitter {
     pairingRequired = false;
     clientId;
     clientName;
+    clientVersion;
+    user;
     capabilities = [];
     pendingRequests = new Map();
     constructor(socket, options) {
@@ -17,25 +21,34 @@ export class ExtensionSession extends EventEmitter {
         this.options = options;
     }
     start() {
-        this.socket.on('message', (data) => void this.handleMessage(data).catch((error) => this.reportError(error)));
+        this.socket.on('message', (data) => {
+            this.handleMessage(data).catch((error) => this.reportError(error));
+        });
         this.socket.on('error', (error) => this.reportError(error));
         this.socket.on('close', (code, reason) => {
             this.rejectPending(new BridgeError('ExtensionDisconnected', 'Tapicker Extension disconnected', { status: 503 }));
             this.emit('close', { code, reason: reason.toString() });
         });
     }
+    /**
+     * 判断底层连接是否仍可用，供会话筛选和命令发送使用。
+     */
+    isConnected() {
+        return this.socket.readyState === this.socket.OPEN;
+    }
     getStatus() {
         return {
-            connected: this.socket.readyState === this.socket.OPEN,
             ready: this.ready,
             pairingRequired: this.pairingRequired,
             clientId: this.clientId,
             clientName: this.clientName,
+            clientVersion: this.clientVersion,
+            user: this.ready && !this.pairingRequired ? this.user : undefined,
             capabilities: this.ready ? this.capabilities : [],
         };
     }
     request(type, data, timeout = DEFAULT_REQUEST_TIMEOUT) {
-        if (!this.ready || this.socket.readyState !== this.socket.OPEN) {
+        if (!this.ready || !this.isConnected()) {
             return Promise.reject(new BridgeError('ExtensionUnavailable', 'No paired Tapicker Extension is connected', { status: 503 }));
         }
         const envelope = createEnvelope(type, data);
@@ -90,9 +103,42 @@ export class ExtensionSession extends EventEmitter {
                 pending.resolve(result.data.data);
             }
             else {
-                pending.reject(new BridgeError(result.data.error.code, result.data.error.message, {
-                    status: 502,
-                    details: result.data.error.details,
+                const { error } = result.data;
+                const upstream = UpstreamErrorDetailsSchema.safeParse(error.details);
+                if (upstream.success) {
+                    const { upstreamStatus, ...details } = upstream.data;
+                    pending.reject(new BridgeError(error.code, error.message, {
+                        status: upstreamStatus === 401 ? 403 : upstreamStatus,
+                        details: Object.keys(details).length > 0 ? details : undefined,
+                    }));
+                    return;
+                }
+                const code = ['InvalidArgument', 'InvalidBridgeMessage'].includes(error.code) ? 'InvalidArguments' : error.code;
+                const statuses = {
+                    InvalidArguments: 400,
+                    PermissionDenied: 403,
+                    SignInRequired: 403,
+                    EmailNotVerified: 403,
+                    AccountBanned: 403,
+                    ExportQuotaExceeded: 403,
+                    DataResultTooLarge: 413,
+                    ExportTooLarge: 413,
+                    WorkflowNotFound: 404,
+                    NotFound: 404,
+                    WorkflowConflict: 409,
+                    DataTableInUse: 409,
+                    WorkflowRunChanged: 409,
+                    WorkflowStartInProgress: 409,
+                    WorkflowAlreadyRunning: 409,
+                    WorkflowCleanupInProgress: 409,
+                    ProcessStopped: 409,
+                    NetworkError: 502,
+                    RequestTimeout: 504,
+                    WorkflowStartTimeout: 504,
+                };
+                pending.reject(new BridgeError(code, error.message, {
+                    status: Object.hasOwn(statuses, code) ? statuses[code] : 502,
+                    details: error.details,
                 }));
             }
             return;
@@ -123,6 +169,8 @@ export class ExtensionSession extends EventEmitter {
         const hello = parsed.data;
         this.clientId = hello.clientId;
         this.clientName = hello.clientName;
+        this.clientVersion = hello.clientVersion;
+        this.user = hello.user;
         this.capabilities = hello.capabilities;
         const accepted = Boolean(hello.credential && this.options.verifyCredential(hello.clientId, hello.credential));
         this.pairingRequired = !accepted;
@@ -147,7 +195,7 @@ export class ExtensionSession extends EventEmitter {
             return;
         }
         const input = parsed.data;
-        if (!this.clientId || input.clientId !== this.clientId || input.clientName !== this.clientName) {
+        if (!this.clientId || input.clientId !== this.clientId) {
             this.respond(message, `${message.type}:res`, safeError(new BridgeError('PairingSessionMismatch', 'Pairing request does not match the Extension hello', {
                 status: 400,
             })));
@@ -183,7 +231,7 @@ export class ExtensionSession extends EventEmitter {
         this.send(createEnvelope(type, data, { id: request.id, callback: false }));
     }
     send(envelope) {
-        if (this.socket.readyState !== this.socket.OPEN) {
+        if (!this.isConnected()) {
             throw new BridgeError('ExtensionUnavailable', 'Tapicker Extension WebSocket is not open', { status: 503 });
         }
         this.socket.send(JSON.stringify(envelope));