@tapicker/bridge 1.0.0

package/src/protocol/schema.ts

@@ -0,0 +1,202 @@
+import { z } from 'zod'
+import { randomUUID } from 'node:crypto'
+import { PROTOCOL_VERSION } from '../constants.js'
+
+export const MessageEnvelopeSchema = z
+  .object({
+    id: z.string().min(1),
+    time: z.number().int().nonnegative(),
+    type: z.string().min(1),
+    data: z.unknown().optional(),
+    cb: z.literal(false).optional(),
+  })
+  .strict()
+
+export type MessageEnvelope = z.infer<typeof MessageEnvelopeSchema>
+
+export const SafeResultSchema = z.union([
+  z
+    .object({
+      ok: z.literal(true),
+      data: z.unknown().optional(),
+    })
+    .strict(),
+  z
+    .object({
+      ok: z.literal(false),
+      error: z
+        .object({
+          code: z.string().min(1),
+          message: z.string(),
+          details: z.unknown().optional(),
+        })
+        .strict(),
+    })
+    .strict(),
+])
+
+export type SafeResult = z.infer<typeof SafeResultSchema>
+
+export const ExtensionHelloInputSchema = z
+  .object({
+    clientId: z.uuid(),
+    clientName: z.string().trim().min(1).max(80),
+    credential: z.string().min(1).optional(),
+    extensionVersion: z.string().min(1).optional(),
+    capabilities: z.array(z.string().min(1)).default([]),
+  })
+  .strict()
+
+export type ExtensionHelloInput = z.infer<typeof ExtensionHelloInputSchema>
+
+export const ExtensionPairInputSchema = z
+  .object({
+    clientId: z.uuid(),
+    clientName: z.string().trim().min(1).max(80),
+    pairingCode: z.string().regex(/^\d{4}$/),
+  })
+  .strict()
+
+export type ExtensionPairInput = z.infer<typeof ExtensionPairInputSchema>
+
+export const BridgeHelloDataSchema = z
+  .object({
+    accepted: z.boolean(),
+    requiresPairing: z.boolean(),
+    bridgeVersion: z.string().min(1),
+    protocolVersion: z.literal(PROTOCOL_VERSION),
+    capabilities: z.array(z.string().min(1)),
+  })
+  .strict()
+
+export const BridgePairDataSchema = z
+  .object({
+    accepted: z.literal(true),
+    clientId: z.uuid(),
+    credential: z.string().min(1),
+  })
+  .strict()
+
+export const TabTargetSchema = z.discriminatedUnion('mode', [
+  z.object({ mode: z.literal('active') }).strict(),
+  z.object({ mode: z.literal('new') }).strict(),
+  z.object({ mode: z.literal('id'), tabId: z.number().int().positive() }).strict(),
+])
+
+export const WorkflowStartInputSchema = z
+  .object({
+    workflowId: z.string().min(1),
+    args: z.record(z.string(), z.unknown()).default({}),
+    tab: TabTargetSchema.default({ mode: 'active' }),
+  })
+  .strict()
+
+export type WorkflowStartInput = z.infer<typeof WorkflowStartInputSchema>
+
+export const WorkflowControlInputSchema = z
+  .object({
+    workflowId: z.string().min(1),
+  })
+  .strict()
+
+export type WorkflowControlInput = z.infer<typeof WorkflowControlInputSchema>
+
+export const DataInputSchema = z
+  .object({
+    tableId: z.string().trim().min(1).max(128),
+  })
+  .strict()
+
+export type DataInput = z.infer<typeof DataInputSchema>
+
+export const WorkflowLifecycleStateSchema = z.enum(['running', 'paused', 'stopping', 'completed', 'stopped', 'failed'])
+
+export const WorkflowStatusDataSchema = z
+  .object({
+    workflowId: z.string().min(1),
+    state: WorkflowLifecycleStateSchema,
+    updatedAt: z.iso.datetime(),
+  })
+  .strict()
+
+export type WorkflowStatusData = z.infer<typeof WorkflowStatusDataSchema>
+
+export const WorkflowStatusEventSchema = z
+  .object({
+    clientId: z.uuid(),
+    ...WorkflowStatusDataSchema.shape,
+  })
+  .strict()
+
+export type WorkflowStatusEvent = z.infer<typeof WorkflowStatusEventSchema>
+
+export const WorkflowWatchRequestSchema = z
+  .object({
+    clientId: z.uuid().optional(),
+    input: WorkflowControlInputSchema,
+  })
+  .strict()
+
+export type WorkflowWatchRequest = z.infer<typeof WorkflowWatchRequestSchema>
+
+export const WorkflowStartResultSchema = z
+  .object({
+    clientId: z.uuid(),
+    workflowId: z.string().min(1),
+    workflowName: z.string().min(1),
+    state: z.enum(['accepted', 'starting', 'running']).optional(),
+  })
+  .strict()
+
+export type WorkflowStartResult = z.infer<typeof WorkflowStartResultSchema>
+
+export function createEnvelope<TData>(
+  type: string,
+  data: TData,
+  options: { id?: string; callback?: boolean } = {},
+): MessageEnvelope {
+  const envelope: MessageEnvelope = {
+    id: options.id ?? randomUUID(),
+    time: Date.now(),
+    type,
+    data,
+  }
+
+  if (options.callback === false) {
+    envelope.cb = false
+  }
+
+  return envelope
+}
+
+export function parseEnvelope(data: unknown) {
+  let value = data
+
+  if (Buffer.isBuffer(value)) {
+    value = value.toString('utf8')
+  }
+
+  if (typeof value === 'string') {
+    try {
+      value = JSON.parse(value) as unknown
+    } catch {
+      return {
+        success: false as const,
+        error: new Error('WebSocket message is not valid JSON'),
+      }
+    }
+  }
+
+  const result = MessageEnvelopeSchema.safeParse(value)
+  if (!result.success) {
+    return {
+      success: false as const,
+      error: result.error,
+    }
+  }
+
+  return {
+    success: true as const,
+    data: result.data,
+  }
+}