@skopon-cool/form-sdk 0.2.4 → 0.3.0

package/src/runtime/formRuntimeContext.tsx

@@ -0,0 +1,107 @@
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useMemo,
+  useRef,
+  type ReactNode,
+} from 'react'
+import type { FormRuntimeWsClient } from './formRuntimeWs'
+import type { FormRuntimeEventData } from './types'
+
+export interface FormRuntimeContextValue {
+  reportEvent: (event: FormRuntimeEventData) => void
+  reportData: (values: Record<string, unknown>) => void
+  runAutoControl: <T>(fn: () => T) => T
+  isAutoControl: () => boolean
+}
+
+const FormRuntimeContext = createContext<FormRuntimeContextValue | null>(null)
+
+const noopRuntime: FormRuntimeContextValue = {
+  reportEvent: () => {},
+  reportData: () => {},
+  runAutoControl: (fn) => fn(),
+  isAutoControl: () => false,
+}
+
+function omitUndefinedValues(
+  values: Record<string, unknown>,
+): Record<string, unknown> {
+  const out: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(values)) {
+    if (value !== undefined) out[key] = value
+  }
+  return out
+}
+
+export interface FormRuntimeProviderProps {
+  client: FormRuntimeWsClient | null
+  children: ReactNode
+}
+
+export function FormRuntimeProvider({
+  client,
+  children,
+}: FormRuntimeProviderProps) {
+  const autoControlDepthRef = useRef(0)
+  const clientRef = useRef(client)
+  clientRef.current = client
+
+  const reportEvent = useCallback((event: FormRuntimeEventData) => {
+    const ws = clientRef.current
+    if (!ws) return
+    const data: Record<string, unknown> = {
+      action: event.action,
+      component: event.component,
+    }
+    if (event.field !== undefined) data.field = event.field
+    if (event.value !== undefined) data.value = event.value
+    const type =
+      autoControlDepthRef.current > 0
+        ? 'form_auto_control_bac_event'
+        : 'form_runtime_event'
+    ws.send(type, data)
+  }, [])
+
+  const reportData = useCallback((values: Record<string, unknown>) => {
+    const ws = clientRef.current
+    if (!ws) return
+    ws.send('form_runtime_data', omitUndefinedValues(values))
+  }, [])
+
+  const runAutoControl = useCallback(<T,>(fn: () => T): T => {
+    autoControlDepthRef.current += 1
+    try {
+      return fn()
+    } finally {
+      autoControlDepthRef.current = Math.max(0, autoControlDepthRef.current - 1)
+    }
+  }, [])
+
+  const isAutoControl = useCallback(
+    () => autoControlDepthRef.current > 0,
+    [],
+  )
+
+  const value = useMemo(
+    (): FormRuntimeContextValue => ({
+      reportEvent,
+      reportData,
+      runAutoControl,
+      isAutoControl,
+    }),
+    [reportEvent, reportData, runAutoControl, isAutoControl],
+  )
+
+  return (
+    <FormRuntimeContext.Provider value={value}>
+      {children}
+    </FormRuntimeContext.Provider>
+  )
+}
+
+/** 无 Provider 时 no-op（表单管理端预览不受影响）。 */
+export function useFormRuntime(): FormRuntimeContextValue {
+  return useContext(FormRuntimeContext) ?? noopRuntime
+}

package/src/runtime/formRuntimeWs.ts

@@ -0,0 +1,158 @@
+import type {
+  FormAutoControlEventData,
+  FormRuntimeEnvelope,
+  FormRuntimeOutboundType,
+} from './types'
+
+const SEND_QUEUE_MAX = 100
+const RECONNECT_MAX_MS = 30_000
+
+export type FormAutoControlHandler = (
+  data: FormAutoControlEventData,
+  envelope: FormRuntimeEnvelope<FormAutoControlEventData>,
+) => void
+
+export interface FormRuntimeWsClientOptions {
+  url: string
+  askUserMessageId: string
+  onAutoControl?: FormAutoControlHandler
+}
+
+export class FormRuntimeWsClient {
+  private readonly url: string
+  private readonly askUserMessageId: string
+  private readonly onAutoControl?: FormAutoControlHandler
+  private ws: WebSocket | null = null
+  private closed = false
+  private reconnectAttempt = 0
+  private reconnectTimer: ReturnType<typeof setTimeout> | null = null
+  private sendQueue: string[] = []
+
+  constructor(options: FormRuntimeWsClientOptions) {
+    this.url = options.url
+    this.askUserMessageId = options.askUserMessageId
+    this.onAutoControl = options.onAutoControl
+  }
+
+  connect(): void {
+    if (this.closed || typeof WebSocket === 'undefined') return
+    this.clearReconnectTimer()
+    try {
+      const ws = new WebSocket(this.url)
+      this.ws = ws
+      ws.onopen = () => {
+        this.reconnectAttempt = 0
+        this.flushQueue()
+      }
+      ws.onmessage = (event) => {
+        this.handleMessage(event.data)
+      }
+      ws.onclose = () => {
+        this.ws = null
+        this.scheduleReconnect()
+      }
+      ws.onerror = () => {
+        // onclose will follow; avoid noisy logs
+      }
+    } catch (error) {
+      console.warn('[FormRuntimeWs] connect failed', error)
+      this.scheduleReconnect()
+    }
+  }
+
+  send(
+    type: FormRuntimeOutboundType,
+    data: Record<string, unknown>,
+  ): void {
+    if (this.closed) return
+    const payload: FormRuntimeEnvelope = {
+      type,
+      ask_user_message_id: this.askUserMessageId,
+      data,
+    }
+    let serialized: string
+    try {
+      serialized = JSON.stringify(payload)
+    } catch (error) {
+      console.warn('[FormRuntimeWs] serialize failed', error)
+      return
+    }
+    if (this.ws?.readyState === WebSocket.OPEN) {
+      this.ws.send(serialized)
+      return
+    }
+    this.enqueue(serialized)
+  }
+
+  close(): void {
+    this.closed = true
+    this.clearReconnectTimer()
+    this.sendQueue = []
+    if (this.ws) {
+      this.ws.onopen = null
+      this.ws.onmessage = null
+      this.ws.onclose = null
+      this.ws.onerror = null
+      try {
+        this.ws.close()
+      } catch {
+        // ignore
+      }
+      this.ws = null
+    }
+  }
+
+  private enqueue(serialized: string): void {
+    this.sendQueue.push(serialized)
+    while (this.sendQueue.length > SEND_QUEUE_MAX) {
+      this.sendQueue.shift()
+    }
+  }
+
+  private flushQueue(): void {
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN) return
+    const pending = this.sendQueue
+    this.sendQueue = []
+    for (const item of pending) {
+      this.ws.send(item)
+    }
+  }
+
+  private scheduleReconnect(): void {
+    if (this.closed) return
+    this.clearReconnectTimer()
+    const delay = Math.min(
+      RECONNECT_MAX_MS,
+      1000 * 2 ** Math.min(this.reconnectAttempt, 5),
+    )
+    this.reconnectAttempt += 1
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null
+      this.connect()
+    }, delay)
+  }
+
+  private clearReconnectTimer(): void {
+    if (this.reconnectTimer != null) {
+      clearTimeout(this.reconnectTimer)
+      this.reconnectTimer = null
+    }
+  }
+
+  private handleMessage(raw: unknown): void {
+    if (typeof raw !== 'string') return
+    let parsed: unknown
+    try {
+      parsed = JSON.parse(raw)
+    } catch {
+      return
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return
+    const envelope = parsed as FormRuntimeEnvelope<FormAutoControlEventData>
+    if (envelope.type !== 'form_auto_control_event') return
+    if (String(envelope.ask_user_message_id ?? '') !== this.askUserMessageId) return
+    const data = envelope.data
+    if (!data || typeof data !== 'object' || Array.isArray(data)) return
+    this.onAutoControl?.(data, envelope)
+  }
+}

package/src/runtime/types.ts

@@ -0,0 +1,26 @@
+export type FormRuntimeAction = 'focus' | 'change' | 'select' | 'click' | 'submit'
+
+export interface FormRuntimeEventData {
+  action: FormRuntimeAction
+  component: string
+  field?: string
+  value?: unknown
+}
+
+export interface FormAutoControlEventData {
+  action: FormRuntimeAction
+  field?: string
+  value?: unknown
+  component?: string
+}
+
+export type FormRuntimeOutboundType =
+  | 'form_runtime_data'
+  | 'form_runtime_event'
+  | 'form_auto_control_bac_event'
+
+export interface FormRuntimeEnvelope<T = Record<string, unknown>> {
+  type: string
+  ask_user_message_id: string
+  data: T
+}

package/src/submit/buildCurlStatement.ts

@@ -7,12 +7,25 @@ function escapeSingleQuotes(text: string): string {
   return text.replace(/'/g, `'\\''`)
 }
 
-export function buildCurlStatement(payload: unknown, callbackUrl?: string | null): string {
+function resolveAuthorizationCurlHeader(headers?: Record<string, string>): string {
+  const authorization = headers?.Authorization?.trim()
+  if (authorization) {
+    return `  -H 'Authorization: ${escapeSingleQuotes(authorization)}' \\`
+  }
+  return `  -H 'Authorization: Bearer <token>' \\`
+}
+
+export function buildCurlStatement(
+  payload: unknown,
+  callbackUrl?: string | null,
+  headers?: Record<string, string>,
+): string {
   const url = (callbackUrl ?? '').trim() || '<callback_url>'
   const body = JSON.stringify(payload ?? {}, null, 2)
   return [
     `curl -X POST '${url}' \\`,
     `  -H 'Content-Type: application/json' \\`,
+    resolveAuthorizationCurlHeader(headers),
     `  -d '${escapeSingleQuotes(body)}'`,
   ].join('\n')
 }
@@ -29,18 +42,21 @@ export interface BuildAskUserCurlStatementOptions {
   cardValues: Record<string, unknown>
   extraValues?: Record<string, unknown>
   callbackUrl?: string | null
+  headers?: Record<string, string>
 }
 
 export function buildAskUserCurlStatement({
   cardValues,
   extraValues = {},
   callbackUrl,
+  headers,
 }: BuildAskUserCurlStatementOptions): string {
   const url = (callbackUrl ?? '').trim() || '<callback_url>'
   const body = buildAskUserCurlBodyJson(cardValues, extraValues)
   return [
     `curl -X POST '${url}' \\`,
     `  -H 'Content-Type: application/json' \\`,
+    resolveAuthorizationCurlHeader(headers),
     `  -d '${escapeSingleQuotes(body)}'`,
   ].join('\n')
 }
@@ -49,9 +65,10 @@ export function buildAskUserCurlStatement({
 export function buildAskUserSubmitCurlFromPayload(
   payload: unknown,
   callbackUrl?: string | null,
+  headers?: Record<string, string>,
 ): string {
   const def = parsePayloadBlocksJson(payload)
-  if (!def) return buildCurlStatement(payload, callbackUrl)
+  if (!def) return buildCurlStatement(payload, callbackUrl, headers)
   const cardValues = extractExtraBlockValues(def.blocks)
-  return buildAskUserCurlStatement({ cardValues, callbackUrl })
+  return buildAskUserCurlStatement({ cardValues, callbackUrl, headers })
 }

package/src/submit/submit.test.ts

@@ -30,6 +30,16 @@ describe('buildCurlStatement', () => {
     const curl = buildCurlStatement({ name: "O'Brien" }, 'https://example.com/hook')
     expect(curl).toContain("curl -X POST 'https://example.com/hook'")
     expect(curl).toContain("O'\\''Brien")
+    expect(curl).toContain("Authorization: Bearer <token>")
+  })
+
+  it('includes Authorization header when provided', () => {
+    const curl = buildCurlStatement(
+      { a: 1 },
+      'https://example.com/hook',
+      { Authorization: 'Bearer tok-1' },
+    )
+    expect(curl).toContain("Authorization: Bearer tok-1")
   })
 
   it('uses placeholder when callback url missing', () => {
@@ -90,6 +100,21 @@ describe('buildAskUserSubmitCurlFromPayload', () => {
       buildCurlStatement(payload, callbackUrl),
     )
   })
+
+  it('includes Authorization header in submit-fields curl', () => {
+    const payload = {
+      title: 'Ask',
+      blocks: [
+        { id: 'p1', type: 'text', name: 'video_title', label: '标题', defaultValue: 'hello' },
+      ],
+    }
+    const curl = buildAskUserSubmitCurlFromPayload(
+      payload,
+      'https://example.com/hook',
+      { Authorization: 'Bearer tok-1' },
+    )
+    expect(curl).toContain("Authorization: Bearer tok-1")
+  })
 })
 
 describe('parsePayloadBlocksJson', () => {
@@ -409,6 +434,35 @@ describe('submitAnswerAgent', () => {
       'callback_url 为空，无法提交',
     )
   })
+
+  it('throws when explicit answer agent callback url is empty', async () => {
+    await expect(
+      submitAnswerAgent(
+        {
+          mission_id: 1,
+          tenant_id: 1001,
+          tenant_user_id: 'u1',
+          request_id: 'req-1',
+          callback_url: 'https://example.com/cb',
+          answer: {},
+        },
+        { answerAgentCallbackUrl: '   ' },
+      ),
+    ).rejects.toThrow('answer_agent_callback_url 未配置，无法提交')
+  })
+
+  it('throws when answer agent callback url cannot be resolved', async () => {
+    await expect(
+      submitAnswerAgent({
+        mission_id: 1,
+        tenant_id: 1001,
+        tenant_user_id: 'u1',
+        request_id: 'req-1',
+        callback_url: 'https://example.com/cb',
+        answer: {},
+      }),
+    ).rejects.toThrow('answer_agent_callback_url 未配置，无法提交')
+  })
 })
 
 describe('submitFormJson', () => {
@@ -434,6 +488,33 @@ describe('submitFormJson', () => {
       }),
     )
   })
+
+  it('POSTs JSON payload with Authorization header', async () => {
+    const fetchMock = vi.fn(async () => ({
+      ok: true,
+      status: 200,
+      headers: { get: () => 'application/json' },
+      json: async () => ({ ok: true }),
+    })) as unknown as typeof fetch
+
+    await submitFormJson(
+      'https://example.com/hook',
+      { a: 1 },
+      {
+        fetch: fetchMock,
+        headers: { Authorization: 'Bearer tok-1' },
+      },
+    )
+    expect(fetchMock).toHaveBeenCalledWith(
+      'https://example.com/hook',
+      expect.objectContaining({
+        headers: expect.objectContaining({
+          Authorization: 'Bearer tok-1',
+          'Content-Type': 'application/json',
+        }),
+      }),
+    )
+  })
 })
 
 describe('validateFormSubmitValues', () => {

package/src/submit/submitAnswerAgent.ts

@@ -1,7 +1,6 @@
 import {
-  DEFAULT_ANSWER_AGENT_CALLBACK_URL,
   resolveAnswerAgentCallbackUrl,
-  resolveSkoponAuthHeaders,
+  resolveSubmitAuthHeaders,
   type SkoponAuthStorageOptions,
 } from '../client/authStorage'
 import { validateAnswerAgentBody } from './buildAnswerAgentBody'
@@ -17,6 +16,25 @@ export interface SubmitAnswerAgentOptions extends SubmitFormJsonOptions {
   answerAgentCallbackUrl?: string | null
 }
 
+const ANSWER_AGENT_CALLBACK_URL_MISSING_ERROR =
+  'answer_agent_callback_url 未配置，无法提交'
+
+function resolveSubmitAnswerAgentUrl(options?: SubmitAnswerAgentOptions): string {
+  if (options?.answerAgentCallbackUrl != null) {
+    const explicit = options.answerAgentCallbackUrl.trim()
+    if (!explicit) {
+      throw new Error(ANSWER_AGENT_CALLBACK_URL_MISSING_ERROR)
+    }
+    return explicit
+  }
+
+  const resolved = resolveAnswerAgentCallbackUrl(options?.authStorage).trim()
+  if (!resolved) {
+    throw new Error(ANSWER_AGENT_CALLBACK_URL_MISSING_ERROR)
+  }
+  return resolved
+}
+
 interface AnswerAgentResponseData {
   callback_ok?: boolean
   callback_status?: number
@@ -79,20 +97,11 @@ export async function submitAnswerAgent(
     throw new Error(validationError)
   }
 
-  const url = (
-    options?.answerAgentCallbackUrl?.trim() ||
-    resolveAnswerAgentCallbackUrl(options?.authStorage) ||
-    DEFAULT_ANSWER_AGENT_CALLBACK_URL
-  ).trim()
-
-  const storageHeaders = resolveSkoponAuthHeaders(options?.authStorage)
+  const url = resolveSubmitAnswerAgentUrl(options)
 
   const result = await submitFormJson(url, body, {
     ...options,
-    headers: {
-      ...storageHeaders,
-      ...(options?.headers ?? {}),
-    },
+    headers: resolveSubmitAuthHeaders(options?.headers, options?.authStorage),
   })
 
   const data = extractAnswerAgentData(result.body)