@tapicker/bridge 1.0.0 → 1.1.0

package/src/commands.ts

@@ -1,158 +0,0 @@
-import { z } from 'zod'
-import { DEFAULT_WORKFLOW_WATCH_WS_PATH } from './constants.js'
-import { BridgeError } from './errors.js'
-import {
-  WorkflowControlInputSchema,
-  DataInputSchema,
-  WorkflowStartInputSchema,
-  WorkflowStartResultSchema,
-  WorkflowStatusDataSchema,
-  WorkflowWatchRequestSchema,
-} from './protocol/schema.js'
-import type { BridgeService } from './bridge/bridge-service.js'
-import type { WorkflowControlInput, WorkflowStartInput } from './protocol/schema.js'
-
-export type CommandContext = {
-  bridge: BridgeService
-}
-
-type CommandDefinition = {
-  description: string
-  schema: z.ZodType
-  execute: (input: unknown, context: CommandContext, clientId?: string) => Promise<unknown>
-}
-
-const CommandRequestSchema = z
-  .object({
-    clientId: z.uuid().optional(),
-    input: z.unknown(),
-  })
-  .strict()
-
-const commandDefinitions: Record<string, CommandDefinition> = {
-  'workflow.start': {
-    description: 'Start one Workflow in a selected connected Tapicker Extension',
-    schema: WorkflowStartInputSchema,
-    execute: async (input, context, clientId) => {
-      const { clientId: selectedClientId, result } = await context.bridge.sendCommandWithClientId(
-        'workflow.start',
-        input,
-        clientId,
-      )
-      if (!result || typeof result !== 'object' || Array.isArray(result)) {
-        throw new BridgeError('InvalidExtensionResponse', 'Extension returned an invalid workflow.start response', {
-          status: 502,
-        })
-      }
-
-      const parsed = WorkflowStartResultSchema.safeParse({ ...result, clientId: selectedClientId })
-      if (!parsed.success || parsed.data.workflowId !== (input as WorkflowStartInput).workflowId) {
-        throw new BridgeError('InvalidExtensionResponse', 'Extension returned an invalid workflow.start response', {
-          status: 502,
-          details: parsed.success
-            ? {
-                requestedWorkflowId: (input as WorkflowStartInput).workflowId,
-                returnedWorkflowId: parsed.data.workflowId,
-              }
-            : parsed.error.issues,
-        })
-      }
-
-      return parsed.data
-    },
-  },
-  'workflow.pause': {
-    description: 'Pause a running Workflow in a selected connected Tapicker Extension',
-    schema: WorkflowControlInputSchema,
-    execute: (input, context, clientId) => context.bridge.sendCommand('workflow.pause', input, clientId),
-  },
-  'workflow.resume': {
-    description: 'Resume a paused Workflow in a selected connected Tapicker Extension',
-    schema: WorkflowControlInputSchema,
-    execute: (input, context, clientId) => context.bridge.sendCommand('workflow.resume', input, clientId),
-  },
-  'workflow.stop': {
-    description: 'Stop a running Workflow in a selected connected Tapicker Extension',
-    schema: WorkflowControlInputSchema,
-    execute: (input, context, clientId) => context.bridge.sendCommand('workflow.stop', input, clientId),
-  },
-  'workflow.status': {
-    description: 'Get the current or most recently persisted Workflow status',
-    schema: WorkflowControlInputSchema,
-    execute: async (input, context, clientId) => {
-      const result = await context.bridge.sendCommand('workflow.status.get', input, clientId)
-      const parsed = WorkflowStatusDataSchema.safeParse(result)
-      if (!parsed.success || parsed.data.workflowId !== (input as WorkflowControlInput).workflowId) {
-        throw new BridgeError('InvalidExtensionResponse', 'Extension returned an invalid workflow status response', {
-          status: 502,
-          details: parsed.success ? undefined : parsed.error.issues,
-        })
-      }
-      return parsed.data
-    },
-  },
-  'data.get': {
-    description: 'Get an extracted data table by tableId; the rows count against the Extension export quota',
-    schema: DataInputSchema,
-    execute: (input, context, clientId) => context.bridge.sendCommand('data.get', input, clientId),
-  },
-  'data.delete': {
-    description: 'Delete an extracted data table by tableId',
-    schema: DataInputSchema,
-    execute: (input, context, clientId) => context.bridge.sendCommand('data.delete', input, clientId),
-  },
-}
-
-export function getCommandDefinition(name: string) {
-  return commandDefinitions[name]
-}
-
-export async function dispatchCommand(name: string, rawInput: unknown, context: CommandContext) {
-  const definition = getCommandDefinition(name)
-  if (!definition) {
-    throw new BridgeError('CommandNotFound', `Unsupported command: ${name}`, { status: 404 })
-  }
-
-  const request = CommandRequestSchema.safeParse(rawInput)
-  if (!request.success) {
-    throw new BridgeError('InvalidArguments', `Invalid command request for ${name}`, {
-      status: 400,
-      details: request.error.issues,
-    })
-  }
-
-  const parsed = definition.schema.safeParse(request.data.input)
-  if (!parsed.success) {
-    throw new BridgeError('InvalidArguments', `Invalid arguments for ${name}`, {
-      status: 400,
-      details: parsed.error.issues,
-    })
-  }
-
-  return definition.execute(parsed.data, context, request.data.clientId)
-}
-
-export function getCommandCapabilities() {
-  return [
-    ...Object.entries(commandDefinitions).map(([name, definition]) => ({
-      name,
-      description: definition.description,
-      inputSchema: z.toJSONSchema(
-        z
-          .object({
-            clientId: z.uuid().optional(),
-            input: definition.schema,
-          })
-          .strict(),
-        { io: 'input' },
-      ),
-    })),
-    {
-      name: 'workflow.watch',
-      description: 'Watch one Workflow through the workflow.watch WebSocket endpoint',
-      transport: 'websocket',
-      path: DEFAULT_WORKFLOW_WATCH_WS_PATH,
-      inputSchema: z.toJSONSchema(WorkflowWatchRequestSchema, { io: 'input' }),
-    },
-  ]
-}

package/src/constants.ts

@@ -1,10 +0,0 @@
-export const VERSION = '1.0.0'
-export const PROTOCOL_VERSION = 1
-
-export const DEFAULT_HOST = '127.0.0.1'
-export const DEFAULT_PORT = 9520
-export const DEFAULT_PORT_MAX = 9530
-export const DEFAULT_WS_PATH = '/ws'
-export const DEFAULT_WORKFLOW_WATCH_WS_PATH = '/v1/commands/workflow.watch'
-export const DEFAULT_MCP_PATH = '/mcp'
-export const DEFAULT_REQUEST_TIMEOUT = 30_000

package/src/errors.ts

@@ -1,72 +0,0 @@
-export type BridgeErrorOptions = {
-  status?: number
-  details?: unknown
-  cause?: unknown
-}
-
-export type SerializedBridgeError = {
-  code: string
-  message: string
-  details?: unknown
-}
-
-export class BridgeError extends Error {
-  readonly code: string
-  readonly status: number
-  readonly details: unknown
-
-  constructor(code: string, message: string, options: BridgeErrorOptions = {}) {
-    super(message, { cause: options.cause })
-    this.name = 'BridgeError'
-    this.code = code
-    this.status = options.status ?? 400
-    this.details = options.details
-  }
-}
-
-export function toBridgeError(error: unknown, fallbackCode = 'InternalError', fallbackStatus = 500) {
-  if (error instanceof BridgeError) {
-    return error
-  }
-
-  if (error instanceof Error) {
-    return new BridgeError(fallbackCode, error.message, {
-      status: fallbackStatus,
-      cause: error,
-    })
-  }
-
-  return new BridgeError(fallbackCode, 'An unexpected error occurred', {
-    status: fallbackStatus,
-    details: error,
-    cause: error,
-  })
-}
-
-export function serializeBridgeError(error: unknown): SerializedBridgeError {
-  const bridgeError = toBridgeError(error)
-  const result: SerializedBridgeError = {
-    code: bridgeError.code,
-    message: bridgeError.message,
-  }
-
-  if (bridgeError.details !== undefined) {
-    result.details = bridgeError.details
-  }
-
-  return result
-}
-
-export function safeError(error: unknown) {
-  return {
-    ok: false as const,
-    error: serializeBridgeError(error),
-  }
-}
-
-export function safeSuccess<T>(data: T) {
-  return {
-    ok: true as const,
-    data,
-  }
-}

package/src/index.ts

@@ -1,35 +0,0 @@
-export { BridgeServer } from './server.js'
-export { BridgeService } from './bridge/bridge-service.js'
-export { ExtensionSession } from './bridge/extension-session.js'
-export { dispatchCommand, getCommandCapabilities, getCommandDefinition } from './commands.js'
-export { BridgeError, safeError, safeSuccess, serializeBridgeError } from './errors.js'
-export {
-  BridgeHelloDataSchema,
-  BridgePairDataSchema,
-  DataInputSchema,
-  ExtensionHelloInputSchema,
-  ExtensionPairInputSchema,
-  MessageEnvelopeSchema,
-  SafeResultSchema,
-  TabTargetSchema,
-  WorkflowControlInputSchema,
-  WorkflowLifecycleStateSchema,
-  WorkflowStatusEventSchema,
-  WorkflowStatusDataSchema,
-  WorkflowStartInputSchema,
-  WorkflowStartResultSchema,
-  WorkflowWatchRequestSchema,
-  createEnvelope,
-  parseEnvelope,
-} from './protocol/schema.js'
-export type {
-  DataInput,
-  WorkflowControlInput,
-  WorkflowStartInput,
-  WorkflowStartResult,
-  WorkflowStatusData,
-  WorkflowStatusEvent,
-  WorkflowWatchRequest,
-} from './protocol/schema.js'
-export { connectWorkflowWatch, waitForWorkflowStatus, workflowWatchWebSocketUrl } from './workflow-watch.js'
-export type { WorkflowWatchConnection, WorkflowWatchInput, WorkflowWatchResult } from './workflow-watch.js'

package/src/mcp.ts

@@ -1,386 +0,0 @@
-import { McpServer } from '@modelcontextprotocol/server'
-import { z } from 'zod'
-import { VERSION } from './constants.js'
-import { dispatchCommand } from './commands.js'
-import { BridgeError, safeError, safeSuccess } from './errors.js'
-import type { BridgeService } from './bridge/bridge-service.js'
-import { TabTargetSchema, WorkflowStatusEventSchema } from './protocol/schema.js'
-import type { WorkflowStatusEvent } from './protocol/schema.js'
-import { connectWorkflowWatch, waitForWorkflowStatus, workflowWatchWebSocketUrl } from './workflow-watch.js'
-import type { WorkflowWatchInput, WorkflowWatchResult } from './workflow-watch.js'
-
-export type TapickerMcpApi = {
-  executeCommand: (name: string, request: unknown) => Promise<unknown>
-  listExtensions: () => Promise<unknown[]>
-  watchWorkflow: (
-    input: WorkflowWatchInput,
-    onStatus: (event: WorkflowStatusEvent) => void,
-    signal?: AbortSignal,
-  ) => Promise<WorkflowWatchResult>
-}
-
-export function createBridgeMcpApi(bridge: BridgeService): TapickerMcpApi {
-  return {
-    executeCommand: (name, request) => dispatchCommand(name, request, { bridge }),
-    listExtensions: async () => bridge.getExtensionStatuses(),
-    watchWorkflow: (input, onStatus, signal) => {
-      const clientId = bridge.resolveCommandClientId('workflow.status', input.clientId)
-      return waitForWorkflowStatus({
-        clientId,
-        workflowId: input.workflowId,
-        subscribe: (handleStatus, _handleClose) => {
-          const listener = (event: WorkflowStatusEvent) => {
-            if (event.clientId === clientId && event.workflowId === input.workflowId) handleStatus(event)
-          }
-          bridge.on('workflow.status', listener)
-          return () => bridge.off('workflow.status', listener)
-        },
-        readStatus: async () => {
-          const status = await bridge.sendCommand<unknown>(
-            'workflow.status.get',
-            { workflowId: input.workflowId },
-            clientId,
-          )
-          return parseWorkflowStatusEvent(status, clientId, input.workflowId)
-        },
-        onStatus,
-        timeoutMs: input.timeoutMs,
-        signal,
-      })
-    },
-  }
-}
-
-export function createHttpMcpApi(baseUrl: string, token?: string): TapickerMcpApi {
-  const bridgeUrl = parseBridgeUrl(baseUrl)
-  const headers: Record<string, string> = {}
-  if (token) {
-    headers.Authorization = `Bearer ${token}`
-  }
-
-  const executeCommand = async (name: string, request: unknown) => {
-    const response = await fetchBridge(new URL(`/v1/commands/${encodeURIComponent(name)}`, bridgeUrl), {
-      method: 'POST',
-      headers: { ...headers, 'Content-Type': 'application/json' },
-      body: JSON.stringify(request),
-    })
-    const body = await readBridgeResponse(response)
-
-    if (!response.ok || !body.ok) {
-      throw new BridgeError(body.error?.code ?? 'BridgeRequestFailed', body.error?.message ?? response.statusText, {
-        status: response.status,
-        details: body.error?.details,
-      })
-    }
-
-    return body.data
-  }
-
-  return {
-    executeCommand,
-    listExtensions: async () => {
-      const response = await fetchBridge(new URL('/v1/extensions', bridgeUrl), { headers })
-      const body = await readBridgeResponse(response)
-
-      if (!response.ok || !Array.isArray(body.extensions)) {
-        throw new BridgeError(body.error?.code ?? 'BridgeRequestFailed', body.error?.message ?? response.statusText, {
-          status: response.status,
-          details: body.error?.details,
-        })
-      }
-
-      return body.extensions
-    },
-    watchWorkflow: async (input, onStatus, signal) => {
-      const connection = await connectWorkflowWatch(
-        workflowWatchWebSocketUrl(bridgeUrl),
-        { clientId: input.clientId, workflowId: input.workflowId },
-        token,
-        signal,
-      )
-      try {
-        return await waitForWorkflowStatus({
-          clientId: connection.clientId,
-          workflowId: input.workflowId,
-          subscribe: (handleStatus, handleClose) => {
-            const removeStatusListener = connection.onStatus(handleStatus)
-            const removeCloseListener = connection.onClose(handleClose)
-            return () => {
-              removeStatusListener()
-              removeCloseListener()
-            }
-          },
-          readStatus: async () => {
-            const status = await executeCommand('workflow.status', {
-              clientId: connection.clientId,
-              input: { workflowId: input.workflowId },
-            })
-            return parseWorkflowStatusEvent(status, connection.clientId, input.workflowId)
-          },
-          onStatus,
-          timeoutMs: input.timeoutMs,
-          signal,
-        })
-      } finally {
-        connection.close()
-      }
-    },
-  }
-}
-
-export function createTapickerMcpServer(api: TapickerMcpApi) {
-  const server = new McpServer({ name: 'tapicker-bridge', version: VERSION })
-
-  server.registerTool(
-    'extensions_list',
-    {
-      title: 'List connected Extensions',
-      description: 'List connected Tapicker Extensions and their clientId values for targeting Workflow commands.',
-      inputSchema: z.object({}).strict(),
-      annotations: { readOnlyHint: true },
-    },
-    async () => runTool(() => api.listExtensions()),
-  )
-
-  server.registerTool(
-    'workflow_start',
-    {
-      title: 'Start Workflow',
-      description:
-        'Start a Workflow in a connected Tapicker Extension. Returns the workflowId, full workflowName, and target clientId. If multiple Extensions are connected, provide clientId.',
-      inputSchema: z
-        .object({
-          workflowId: z.string().min(1).describe('The Workflow ID to start.'),
-          args: z.record(z.string(), z.unknown()).optional().describe('Optional Workflow input arguments.'),
-          tab: TabTargetSchema.optional().describe('Browser tab target; defaults to the active tab.'),
-          clientId: z
-            .uuid()
-            .optional()
-            .describe('Target Extension UUID; required when multiple Extensions are connected.'),
-        })
-        .strict(),
-      annotations: { destructiveHint: true },
-    },
-    async ({ clientId, ...input }) => runTool(() => api.executeCommand('workflow.start', { clientId, input })),
-  )
-
-  for (const action of ['pause', 'resume', 'stop'] as const) {
-    server.registerTool(
-      `workflow_${action}`,
-      {
-        title: `${capitalize(action)} Workflow`,
-        description: `${capitalize(action)} a Workflow by workflowId. If multiple Extensions are connected, provide clientId.`,
-        inputSchema: z
-          .object({
-            workflowId: z.string().min(1).describe('The Workflow ID to control.'),
-            clientId: z
-              .uuid()
-              .optional()
-              .describe('Target Extension UUID; required when multiple Extensions are connected.'),
-          })
-          .strict(),
-        annotations: action === 'stop' ? { destructiveHint: true } : undefined,
-      },
-      async ({ clientId, ...input }) => runTool(() => api.executeCommand(`workflow.${action}`, { clientId, input })),
-    )
-  }
-
-  server.registerTool(
-    'workflow_status',
-    {
-      title: 'Get Workflow status',
-      description:
-        'Get the current or most recently persisted status for a Workflow. If multiple Extensions are connected, provide clientId.',
-      inputSchema: z
-        .object({
-          workflowId: z.string().min(1).describe('The Workflow ID to query.'),
-          clientId: z
-            .uuid()
-            .optional()
-            .describe('Target Extension UUID; required when multiple Extensions are connected.'),
-        })
-        .strict(),
-      annotations: { readOnlyHint: true },
-    },
-    async ({ clientId, ...input }) => runTool(() => api.executeCommand('workflow.status', { clientId, input })),
-  )
-
-  server.registerTool(
-    'data_get',
-    {
-      title: 'Get extracted data',
-      description:
-        'Get all rows from an extracted data table by tableId. This consumes the export row quota of the connected Extension account. If multiple Extensions are connected, provide clientId.',
-      inputSchema: z
-        .object({
-          tableId: z.string().trim().min(1).max(128).describe('The data table ID copied from Tapicker Data.'),
-          clientId: z
-            .uuid()
-            .optional()
-            .describe('Target Extension UUID; required when multiple Extensions are connected.'),
-        })
-        .strict(),
-    },
-    async ({ clientId, tableId }) => runTool(() => api.executeCommand('data.get', { clientId, input: { tableId } })),
-  )
-
-  server.registerTool(
-    'data_delete',
-    {
-      title: 'Delete extracted data',
-      description:
-        'Delete an extracted data table and remove it from Tapicker Data by tableId. If multiple Extensions are connected, provide clientId.',
-      inputSchema: z
-        .object({
-          tableId: z.string().trim().min(1).max(128).describe('The data table ID copied from Tapicker Data.'),
-          clientId: z
-            .uuid()
-            .optional()
-            .describe('Target Extension UUID; required when multiple Extensions are connected.'),
-        })
-        .strict(),
-      annotations: { destructiveHint: true },
-    },
-    async ({ clientId, tableId }) => runTool(() => api.executeCommand('data.delete', { clientId, input: { tableId } })),
-  )
-
-  server.registerTool(
-    'workflow_watch',
-    {
-      title: 'Wait for Workflow completion',
-      description:
-        'Listen for Workflow status changes until it completes, stops, or fails. Returns the latest status when timeoutMs is reached. If multiple Extensions are connected, provide clientId.',
-      inputSchema: z
-        .object({
-          workflowId: z.string().min(1).describe('The Workflow ID to watch.'),
-          clientId: z
-            .uuid()
-            .optional()
-            .describe('Target Extension UUID; required when multiple Extensions are connected.'),
-          timeoutMs: z
-            .number()
-            .int()
-            .positive()
-            .max(2_147_483_647)
-            .optional()
-            .describe('Optional maximum time to wait in milliseconds.'),
-        })
-        .strict(),
-      annotations: { readOnlyHint: true },
-    },
-    async ({ clientId, workflowId, timeoutMs }, context) => {
-      const progressToken = context.mcpReq._meta?.progressToken
-      let progress = 0
-      let notificationQueue = Promise.resolve()
-      return runTool(async () => {
-        const result = await api.watchWorkflow(
-          { clientId, workflowId, timeoutMs },
-          (event) => {
-            if (progressToken === undefined) return
-            progress += 1
-            notificationQueue = notificationQueue
-              .then(() =>
-                context.mcpReq.notify({
-                  method: 'notifications/progress',
-                  params: {
-                    progressToken,
-                    progress,
-                    message: `Workflow status: ${event.state}`,
-                  },
-                }),
-              )
-              .catch(() => undefined)
-          },
-          context.mcpReq.signal,
-        )
-        await notificationQueue
-        return result
-      })
-    },
-  )
-
-  return server
-}
-
-function parseWorkflowStatusEvent(value: unknown, clientId: string, workflowId: string) {
-  const parsed = WorkflowStatusEventSchema.safeParse({ ...(value as object), clientId })
-  if (!parsed.success || parsed.data.workflowId !== workflowId) {
-    throw new BridgeError('InvalidExtensionResponse', 'Extension returned an invalid workflow status response', {
-      status: 502,
-      details: parsed.success ? undefined : parsed.error.issues,
-    })
-  }
-  return parsed.data
-}
-
-function capitalize(value: string) {
-  return `${value[0].toUpperCase()}${value.slice(1)}`
-}
-
-function parseBridgeUrl(value: string) {
-  let url: URL
-  try {
-    url = new URL(value)
-  } catch (cause) {
-    throw new BridgeError('InvalidBridgeUrl', 'Bridge URL must be a valid HTTP or HTTPS URL', { status: 400, cause })
-  }
-
-  if (url.protocol !== 'http:' && url.protocol !== 'https:') {
-    throw new BridgeError('InvalidBridgeUrl', 'Bridge URL must use HTTP or HTTPS', { status: 400 })
-  }
-  if (url.username || url.password || url.pathname !== '/' || url.search || url.hash) {
-    throw new BridgeError('InvalidBridgeUrl', 'Bridge URL must contain only the HTTP(S) origin and port', {
-      status: 400,
-    })
-  }
-
-  return url
-}
-
-async function fetchBridge(url: URL, init: RequestInit) {
-  try {
-    return await fetch(url, { ...init, signal: AbortSignal.timeout(30_000) })
-  } catch (cause) {
-    throw new BridgeError('BridgeUnavailable', `Unable to reach Tapicker Bridge at ${url.origin}`, {
-      status: 503,
-      cause,
-    })
-  }
-}
-
-async function readBridgeResponse(response: Response) {
-  let body: {
-    ok?: boolean
-    data?: unknown
-    error?: { code?: string; message?: string; details?: unknown }
-    extensions?: unknown[]
-  }
-
-  try {
-    body = (await response.json()) as typeof body
-  } catch (cause) {
-    throw new BridgeError('InvalidBridgeResponse', 'Bridge returned an invalid JSON response', {
-      status: 502,
-      cause,
-    })
-  }
-
-  if (!body || typeof body !== 'object') {
-    throw new BridgeError('InvalidBridgeResponse', 'Bridge returned an invalid response', { status: 502 })
-  }
-
-  return body
-}
-
-async function runTool(operation: () => Promise<unknown>) {
-  try {
-    return {
-      content: [{ type: 'text' as const, text: JSON.stringify(safeSuccess(await operation()), null, 2) }],
-    }
-  } catch (error) {
-    return {
-      content: [{ type: 'text' as const, text: JSON.stringify(safeError(error), null, 2) }],
-      isError: true,
-    }
-  }
-}