@morscherlab/mint-sdk 1.2.0-beta.2 → 1.2.0-beta.20

package/src/composables/useApi.ts

@@ -1,6 +1,7 @@
 import axios, { type AxiosInstance, type AxiosRequestConfig, type InternalAxiosRequestConfig } from 'axios'
 import { useSettingsStore } from '../stores/settings'
 import { useAuthStore } from '../stores/auth'
+import { MintApiError, mintApiErrorFromResponse } from '../apiErrors'
 
 let apiClientInstance: AxiosInstance | null = null
 let interceptorAttached = false
@@ -8,11 +9,13 @@ let interceptorAttached = false
 interface MintAxiosRequestConfig extends AxiosRequestConfig {
   _mintSkipAuth?: boolean
   _mintAuthToken?: string
+  _mintTypedErrors?: boolean
 }
 
 interface MintInternalAxiosRequestConfig extends InternalAxiosRequestConfig {
   _mintSkipAuth?: boolean
   _mintAuthToken?: string
+  _mintTypedErrors?: boolean
 }
 
 type MutableHeaders = Record<string, unknown> & {
@@ -103,14 +106,27 @@ function getAuthorizationHeader(headers: AxiosRequestConfig['headers']): unknown
   return key ? bag[key] : undefined
 }
 
-/** Raised when an authenticated SDK request is rejected because the login is no longer valid. */
-export class AuthenticationRequiredError extends Error {
-  readonly code = 'AUTHENTICATION_REQUIRED'
-  readonly status = 401
-
-  constructor(readonly cause?: unknown) {
-    super('Authentication required. Please sign in again.')
-    this.name = 'AuthenticationRequiredError'
+/**
+ * Raised when an authenticated SDK request is rejected because the login is no
+ * longer valid. It is also a `MintApiError` (status 401), so typed-error callers
+ * and `instanceof AuthenticationRequiredError` callers both recognise it.
+ */
+export class AuthenticationRequiredError extends MintApiError {
+  override readonly name: string = 'AuthenticationRequiredError'
+  declare readonly code: 'AUTHENTICATION_REQUIRED'
+  declare readonly status: 401
+
+  constructor(cause?: unknown, envelope?: MintApiError) {
+    super(
+      'Authentication required. Please sign in again.',
+      'AUTHENTICATION_REQUIRED',
+      401,
+      envelope?.requestId ?? null,
+      envelope?.details ?? null,
+      envelope?.detail,
+      envelope?.body ?? null,
+      cause,
+    )
   }
 }
 
@@ -118,12 +134,13 @@ export class AuthenticationRequiredError extends Error {
 export function authenticationRequiredError(
   cause: unknown,
   rejectedToken?: string,
+  envelope?: MintApiError,
 ): AuthenticationRequiredError {
   const currentAuthStore = useAuthStore()
   if (rejectedToken && currentAuthStore.token === rejectedToken) {
     currentAuthStore.clearToken()
   }
-  return new AuthenticationRequiredError(cause)
+  return new AuthenticationRequiredError(cause, envelope)
 }
 
 function getApiClient(): AxiosInstance {
@@ -141,6 +158,8 @@ export interface ApiClientOptions {
   baseUrl?: string
   timeout?: number
   withAuth?: boolean
+  /** Normalize failed responses into MintApiError. Generated clients enable this by default. */
+  typedErrors?: boolean
 }
 
 export interface UseApiReturn {
@@ -187,11 +206,35 @@ export function useApi(options: ApiClientOptions = {}): UseApiReturn {
     })
     apiClient.interceptors.response.use(
       (response) => response,
-      (error: unknown) => {
-        if (axios.isAxiosError(error) && error.response?.status === 401) {
+      async (error: unknown) => {
+        if (axios.isAxiosError(error) && error.response) {
           const request = error.config as MintInternalAxiosRequestConfig | undefined
-          if (request?._mintSkipAuth !== true) {
-            return Promise.reject(authenticationRequiredError(error, request?._mintAuthToken))
+          if (request?._mintTypedErrors) {
+            let payload: unknown = error.response.data
+            if (payload instanceof Blob) {
+              try {
+                payload = JSON.parse(await payload.text())
+              } catch {
+                // Keep non-JSON download errors available as the original body.
+              }
+            }
+            const typed = mintApiErrorFromResponse(
+              error.response.status,
+              payload,
+              {
+                requestId: String(error.response.headers?.['x-request-id'] ?? '') || null,
+                cause: error,
+              },
+            )
+            if (error.response.status === 401 && request._mintSkipAuth !== true) {
+              return Promise.reject(authenticationRequiredError(error, request._mintAuthToken, typed))
+            }
+            return Promise.reject(typed)
+          }
+          if (error.response.status === 401) {
+            if (request?._mintSkipAuth !== true) {
+              return Promise.reject(authenticationRequiredError(error, request?._mintAuthToken))
+            }
           }
         }
         return Promise.reject(error)
@@ -213,6 +256,7 @@ export function useApi(options: ApiClientOptions = {}): UseApiReturn {
     const base: MintAxiosRequestConfig = {
       baseURL: getBaseUrl(),
       timeout: options.timeout ?? settingsStore.requestTimeout,
+      _mintTypedErrors: options.typedErrors,
       ...config,
     }
     // Strip auth header if explicitly disabled

package/src/composables/useAsync.ts

@@ -165,7 +165,11 @@ function defaultTransformError(error: unknown): AsyncError {
  * const handleSubmit = () => submit(new FormData(formRef.value))
  * ```
  */
-/** Wraps an async function with reactive loading, error, and success state plus optional auto-execute. */
+/**
+ * Wraps an async function with reactive loading, error, and success state plus optional auto-execute.
+ *
+ * @deprecated Unused by the MINT platform and scheduled for removal in MINT 1.3; use `useRequestSyncState()` instead.
+ */
 export function useAsync<T>(
   asyncFn: (...args: unknown[]) => Promise<T>,
   options: UseAsyncOptions<T> = {}

package/src/composables/useAuth.ts

@@ -93,6 +93,7 @@ export function useAuth(): UseAuthReturn {
         passkey_enabled: boolean
         passkey_registered?: boolean
         registration_enabled?: boolean
+        database_mode?: string
         access?: {
           experiment_visibility_mode?: 'open' | 'restricted'
           experimentVisibilityMode?: 'open' | 'restricted'
@@ -104,6 +105,7 @@ export function useAuth(): UseAuthReturn {
         passkeyEnabled: response.data.passkey_enabled,
         passkeyRegistered: response.data.passkey_registered ?? false,
         registrationEnabled: response.data.registration_enabled ?? false,
+        databaseMode: response.data.database_mode ?? 'none',
         experimentVisibilityMode:
           response.data.access?.experiment_visibility_mode
           ?? response.data.access?.experimentVisibilityMode
@@ -119,6 +121,7 @@ export function useAuth(): UseAuthReturn {
         passkeyEnabled: false,
         passkeyRegistered: false,
         registrationEnabled: false,
+        databaseMode: 'none',
         experimentVisibilityMode: 'open',
       }
     }

package/src/composables/useBioTemplatePackWorkspace.ts

@@ -27,6 +27,9 @@ import {
   type BioTemplateWorkspaceBindings,
   type UseBioTemplateWorkspaceReturn,
 } from './useBioTemplateWorkspace'
+import {
+  liftWorkspaceComponentBindings,
+} from './flattenWorkspaceBindings'
 import type {
   BioTemplateComponentBinding,
   BioTemplateComponentBindingsById,
@@ -120,14 +123,17 @@ export function useBioTemplatePackWorkspace(
   const pillNav = computed(() => workspace.value.pillNav)
   const topBarSettings = computed(() => workspace.value.topBarSettings)
   const bindings = computed(() => workspace.value.bindings)
-  const componentBindings = computed(() => workspace.value.componentBindings)
-  const componentBindingsById = computed(() => workspace.value.componentBindingsById)
-  const componentImports = computed(() => workspace.value.componentImports)
-  const componentProps = computed(() => workspace.value.componentProps)
-  const componentPropsById = computed(() => workspace.value.componentPropsById)
-  const componentPropsByComponent = computed(() => workspace.value.componentPropsByComponent)
-  const componentSnippets = computed(() => workspace.value.componentSnippets)
-  const componentUsage = computed(() => workspace.value.componentUsage)
+  const {
+    componentBindings,
+    componentBindingsById,
+    componentImports,
+    componentProps,
+    componentPropsById,
+    componentPropsByComponent,
+    componentSnippets,
+    componentUsage,
+    getComponentProps: getWorkspaceComponentProps,
+  } = liftWorkspaceComponentBindings(workspace)
 
   watch(collection, value => {
     workspaceRef.value = createWorkspace(value)
@@ -181,7 +187,7 @@ export function useBioTemplatePackWorkspace(
     componentPropsByComponent,
     componentSnippets,
     componentUsage,
-    getComponentProps: (component, options) => workspace.value.getComponentProps(component, options),
+    getComponentProps: getWorkspaceComponentProps,
     applyCollection,
     resetToDefaultCollection,
     save: templateCollection.save,

package/src/composables/useBioTemplatePresetWorkspace.ts

@@ -34,6 +34,9 @@ import {
   type BioTemplateRendererBinding,
   type UseBioTemplateWorkspaceReturn,
 } from './useBioTemplateWorkspace'
+import {
+  liftWorkspaceComponentBindings,
+} from './flattenWorkspaceBindings'
 import type {
   BioTemplateComponentBinding,
   BioTemplateComponentBindingsById,
@@ -138,14 +141,17 @@ export function useBioTemplatePresetWorkspace(
   const collection = templateCollection.templateCollection
   const workspace = computed(() => useBioTemplateWorkspace(collection.value, resolvedControlOptions))
   const renderer = computed<BioTemplateRendererBinding>(() => ({ target: collection.value }))
-  const componentBindings = computed(() => workspace.value.componentBindings)
-  const componentBindingsById = computed(() => workspace.value.componentBindingsById)
-  const componentImports = computed(() => workspace.value.componentImports)
-  const componentProps = computed(() => workspace.value.componentProps)
-  const componentPropsById = computed(() => workspace.value.componentPropsById)
-  const componentPropsByComponent = computed(() => workspace.value.componentPropsByComponent)
-  const componentSnippets = computed(() => workspace.value.componentSnippets)
-  const componentUsage = computed(() => workspace.value.componentUsage)
+  const {
+    componentBindings,
+    componentBindingsById,
+    componentImports,
+    componentProps,
+    componentPropsById,
+    componentPropsByComponent,
+    componentSnippets,
+    componentUsage,
+    getComponentProps,
+  } = liftWorkspaceComponentBindings(workspace)
   const form = reactive({
     ...controls.form,
     modelValue: controlValues.value,
@@ -179,13 +185,6 @@ export function useBioTemplatePresetWorkspace(
     ...topBarSettings,
   }))
 
-  function getComponentProps(
-    component: string,
-    options?: Parameters<UseBioTemplateWorkspaceReturn['getComponentProps']>[1],
-  ) {
-    return workspace.value.getComponentProps(component, options)
-  }
-
   const bindings: BioTemplatePresetWorkspaceBindings = {
     renderer,
     form,

package/src/composables/useBioTemplateWorkspace.ts

@@ -21,16 +21,12 @@ import {
 } from './useBioTemplateControls'
 import {
   useBioTemplateComponents,
-  type BioTemplateComponentBinding,
-  type BioTemplateComponentBindingsById,
-  type BioTemplateComponentImport,
-  type BioTemplateComponentPropsByComponent,
-  type BioTemplateComponentPropsBinding,
-  type BioTemplateComponentPropsById,
-  type BioTemplateComponentSnippet,
-  type BioTemplateComponentUsage,
   type UseBioTemplateComponentsReturn,
 } from './useBioTemplateComponents'
+import {
+  flattenWorkspaceComponentBindings,
+  type BioTemplateWorkspaceComponentBindings,
+} from './flattenWorkspaceBindings'
 
 export type BioTemplateWorkspaceTarget = BioTemplateControlTarget
 
@@ -38,24 +34,16 @@ export interface BioTemplateRendererBinding {
   target: BioTemplateEnvelope<unknown> | TemplateCollectionEnvelope
 }
 
-export interface BioTemplateWorkspaceBindings {
+export interface BioTemplateWorkspaceBindings extends BioTemplateWorkspaceComponentBindings {
   renderer: BioTemplateRendererBinding | null
   form: ControlWorkspaceFormBinding
   sidebar: ControlWorkspaceSidebarBinding
   topBar: UseControlWorkspaceReturn<BioTemplateControlSchema>['bindings']['topBar']
   topBarSettings: ControlWorkspaceTopBarSettingsBinding
   pillNav: ControlWorkspacePillNavBinding
-  componentBindings: BioTemplateComponentBinding[]
-  componentBindingsById: BioTemplateComponentBindingsById
-  componentProps: BioTemplateComponentPropsBinding[]
-  componentPropsById: BioTemplateComponentPropsById
-  componentPropsByComponent: BioTemplateComponentPropsByComponent
-  componentSnippets: BioTemplateComponentSnippet[]
-  componentUsage: BioTemplateComponentUsage | null
-  getComponentProps: UseBioTemplateComponentsReturn['getComponentProps']
 }
 
-export interface UseBioTemplateWorkspaceReturn {
+export interface UseBioTemplateWorkspaceReturn extends BioTemplateWorkspaceComponentBindings {
   target: BioTemplateWorkspaceTarget
   controls: UseControlSchemaReturn<BioTemplateControlSchema>
   workspace: UseControlWorkspaceReturn<BioTemplateControlSchema>
@@ -70,15 +58,6 @@ export interface UseBioTemplateWorkspaceReturn {
   topBarSettings: ControlWorkspaceTopBarSettingsBinding
   bindings: BioTemplateWorkspaceBindings
   renderer: BioTemplateRendererBinding | null
-  componentBindings: BioTemplateComponentBinding[]
-  componentBindingsById: BioTemplateComponentBindingsById
-  componentImports: BioTemplateComponentImport[]
-  componentProps: BioTemplateComponentPropsBinding[]
-  componentPropsById: BioTemplateComponentPropsById
-  componentPropsByComponent: BioTemplateComponentPropsByComponent
-  componentSnippets: BioTemplateComponentSnippet[]
-  componentUsage: BioTemplateComponentUsage | null
-  getComponentProps: UseBioTemplateComponentsReturn['getComponentProps']
 }
 
 /** One-stop wiring for BioTemplateRenderer, FormBuilder, AppSidebar, and template-aware SDK components. */
@@ -90,21 +69,25 @@ export function useBioTemplateWorkspace(
   const workspace = useControlWorkspace(controls.controls, options)
   const components = useBioTemplateComponents(target)
   const renderer = isTemplateObjectTarget(target) ? { target } : null
-  const bindings: BioTemplateWorkspaceBindings = {
-    renderer,
-    form: workspace.bindings.form,
-    sidebar: workspace.bindings.sidebar,
-    topBar: workspace.bindings.topBar,
-    topBarSettings: workspace.bindings.topBarSettings,
-    pillNav: workspace.bindings.pillNav,
+  const componentBindings = flattenWorkspaceComponentBindings({
     componentBindings: components.bindings,
     componentBindingsById: components.componentBindingsById,
+    componentImports: components.imports,
     componentProps: components.componentProps,
     componentPropsById: components.componentPropsById,
     componentPropsByComponent: components.componentPropsByComponent,
     componentSnippets: components.snippets,
     componentUsage: components.usage,
     getComponentProps: components.getComponentProps,
+  })
+  const bindings: BioTemplateWorkspaceBindings = {
+    renderer,
+    form: workspace.bindings.form,
+    sidebar: workspace.bindings.sidebar,
+    topBar: workspace.bindings.topBar,
+    topBarSettings: workspace.bindings.topBarSettings,
+    pillNav: workspace.bindings.pillNav,
+    ...componentBindings,
   }
 
   return {
@@ -122,15 +105,7 @@ export function useBioTemplateWorkspace(
     topBarSettings: workspace.topBarSettings,
     bindings,
     renderer,
-    componentBindings: components.bindings,
-    componentBindingsById: components.componentBindingsById,
-    componentImports: components.imports,
-    componentProps: components.componentProps,
-    componentPropsById: components.componentPropsById,
-    componentPropsByComponent: components.componentPropsByComponent,
-    componentSnippets: components.snippets,
-    componentUsage: components.usage,
-    getComponentProps: components.getComponentProps,
+    ...componentBindings,
   }
 }
 

package/src/composables/useCommandHistory.ts

@@ -31,7 +31,11 @@ export interface UseCommandHistoryReturn<TCommand extends CommandHistoryCommand
   clear: () => void
 }
 
-/** Generic command-stack state for plugin editors with undo/redo controls. */
+/**
+ * Generic command-stack state for plugin editors with undo/redo controls.
+ *
+ * @deprecated Unused by the MINT platform and scheduled for removal in MINT 1.3; keep command stacks plugin-local.
+ */
 export function useCommandHistory<TCommand extends CommandHistoryCommand = CommandHistoryCommand>(
   options: UseCommandHistoryOptions = {},
 ): UseCommandHistoryReturn<TCommand> {

package/src/composables/useDropdownState.ts

@@ -1,10 +1,18 @@
-import { ref, type Ref } from 'vue'
+import { nextTick, ref, type Ref } from 'vue'
 import { useEventListener } from './useEventListener'
 
 export interface UseDropdownStateOptions {
   closeOnOutsideClick?: boolean
   closeOnEscape?: boolean
+  /** Close the panel when the page scrolls or the viewport resizes. Default `false`. */
+  closeOnScroll?: boolean
   insideRefs?: Array<Ref<HTMLElement | null>>
+  /**
+   * Element focus returns to when the panel closes with `close(true)` (Escape).
+   * Pass one when the trigger lives outside `rootRef`; otherwise bind the
+   * returned `triggerRef` to the trigger element.
+   */
+  triggerRef?: Ref<HTMLElement | null>
   onOpen?: () => void
   onClose?: () => void
 }
@@ -12,19 +20,29 @@ export interface UseDropdownStateOptions {
 export interface UseDropdownStateReturn {
   isOpen: Ref<boolean>
   rootRef: Ref<HTMLElement | null>
+  /** Bind to the trigger element so Escape can return focus to it. */
+  triggerRef: Ref<HTMLElement | null>
   open: () => void
-  close: () => void
+  /** Closes the panel; `returnFocus` moves focus back to `triggerRef`. */
+  close: (returnFocus?: boolean) => void
   toggle: () => void
   handleClickOutside: (event: MouseEvent) => void
   handleKeydown: (event: KeyboardEvent) => void
 }
 
-/** Shared disclosure state for dropdown-style SDK components. */
+/**
+ * Shared disclosure state for dropdown-style SDK components: open/close state,
+ * outside-click and Escape closing, optional scroll/resize closing, and focus
+ * return to the trigger. `close(returnFocus)` mirrors `useMenuKeyboard`'s
+ * contract, so the two compose directly.
+ */
 export function useDropdownState(options: UseDropdownStateOptions = {}): UseDropdownStateReturn {
   const isOpen = ref(false)
   const rootRef = ref<HTMLElement | null>(null)
+  const triggerRef = options.triggerRef ?? ref<HTMLElement | null>(null)
   const closeOnOutsideClick = options.closeOnOutsideClick ?? true
   const closeOnEscape = options.closeOnEscape ?? true
+  const closeOnScroll = options.closeOnScroll ?? false
 
   function open(): void {
     if (isOpen.value) return
@@ -32,10 +50,13 @@ export function useDropdownState(options: UseDropdownStateOptions = {}): UseDrop
     options.onOpen?.()
   }
 
-  function close(): void {
+  function close(returnFocus = false): void {
     if (!isOpen.value) return
     isOpen.value = false
     options.onClose?.()
+    if (returnFocus) {
+      void nextTick(() => triggerRef.value?.focus())
+    }
   }
 
   function toggle(): void {
@@ -60,20 +81,29 @@ export function useDropdownState(options: UseDropdownStateOptions = {}): UseDrop
 
   function handleKeydown(event: KeyboardEvent): void {
     if (closeOnEscape && event.key === 'Escape') {
-      close()
+      close(true)
     }
   }
 
+  function handleViewportChange(): void {
+    if (isOpen.value) close()
+  }
+
   if (closeOnOutsideClick) {
     useEventListener(() => document, 'click', handleClickOutside)
   }
   if (closeOnEscape) {
     useEventListener(() => document, 'keydown', handleKeydown)
   }
+  if (closeOnScroll) {
+    useEventListener(() => window, 'scroll', handleViewportChange, true)
+    useEventListener(() => window, 'resize', handleViewportChange)
+  }
 
   return {
     isOpen,
     rootRef,
+    triggerRef,
     open,
     close,
     toggle,

package/src/composables/useEventStream.ts

@@ -7,6 +7,7 @@ import {
   shallowRef,
   type Ref,
 } from 'vue'
+import { tryUseSettingsStore } from '../stores/settings'
 
 export type EventStreamTransport = (
   input: RequestInfo | URL,
@@ -26,7 +27,16 @@ export interface EventStreamOptions<TData = string> {
   headers?: HeadersInit
   credentials?: RequestCredentials
   immediate?: boolean
+  /**
+   * Reconnect after a dropped stream. Left unset, it follows the platform's
+   * `wsAutoReconnect` setting, defaulting to `true` without a settings store.
+   */
   reconnect?: boolean
+  /**
+   * Delay before the first reconnect attempt. Left unset, it follows the
+   * platform's `wsReconnectInterval` setting, defaulting to 2000 ms without a
+   * settings store. A server-sent `retry:` field still overrides it.
+   */
   reconnectDelayMs?: number
   parseJson?: boolean
   shouldReconnect?: (cause?: unknown) => boolean
@@ -114,7 +124,9 @@ export function useEventStream<TData = string>(
   let controller: AbortController | null = null
   let reader: ReadableStreamDefaultReader<Uint8Array> | null = null
   let reconnectTimer: ReturnType<typeof setTimeout> | null = null
-  let reconnectDelayMs = options.reconnectDelayMs ?? 2_000
+  const settings = tryUseSettingsStore()
+  const reconnectEnabled = options.reconnect ?? settings?.wsAutoReconnect ?? true
+  let reconnectDelayMs = options.reconnectDelayMs ?? settings?.wsReconnectInterval ?? 2_000
   let stopped = true
   let generation = 0
 
@@ -135,7 +147,7 @@ export function useEventStream<TData = string>(
 
   function scheduleReconnect(connectionGeneration: number, cause?: unknown): void {
     if (stopped || generation !== connectionGeneration) return
-    if (options.reconnect === false || options.shouldReconnect?.(cause) === false) {
+    if (!reconnectEnabled || options.shouldReconnect?.(cause) === false) {
       stopped = true
       return
     }