@morscherlab/mint-sdk 1.0.53 → 1.0.55

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@morscherlab/mint-sdk",
-  "version": "1.0.53",
+  "version": "1.0.55",
   "description": "MINT Platform SDK — Vue 3 components, composables, and types for plugin development. MINT = Mass-spec INtegrated Toolkit.",
   "type": "module",
   "main": "./dist/index.js",

package/src/__tests__/composables/resolvePluginFrontendBase.test.ts

@@ -0,0 +1,65 @@
+import { afterEach, describe, expect, it } from 'vitest'
+
+import { resolvePluginFrontendBase } from '../../composables/pluginFrontendBase'
+
+type InjectedPlatformWindow = Window & {
+  __MINT_PLATFORM__?: unknown
+}
+
+describe('resolvePluginFrontendBase', () => {
+  afterEach(() => {
+    delete (window as InjectedPlatformWindow).__MINT_PLATFORM__
+  })
+
+  it('should use the normalized route prefix when the platform context is integrated', () => {
+    ;(window as InjectedPlatformWindow).__MINT_PLATFORM__ = {
+      isIntegrated: true,
+      theme: 'light',
+      plugin: {
+        id: 'leaf',
+        name: 'LEAF',
+        version: '0.7.0',
+        route_prefix: '/leaf///',
+        api_prefix: '/api/leaf',
+      },
+    }
+
+    expect(resolvePluginFrontendBase('./')).toBe('/leaf/')
+  })
+
+  it('should preserve the caller fallback when the platform context is absent', () => {
+    expect(resolvePluginFrontendBase('./')).toBe('./')
+  })
+
+  it('should preserve the caller fallback when the platform context is standalone', () => {
+    ;(window as InjectedPlatformWindow).__MINT_PLATFORM__ = {
+      isIntegrated: false,
+      theme: 'light',
+      plugin: {
+        id: 'leaf',
+        name: 'LEAF',
+        version: '0.7.0',
+        route_prefix: '/leaf',
+        api_prefix: '/api/leaf',
+      },
+    }
+
+    expect(resolvePluginFrontendBase('/dev/')).toBe('/dev/')
+  })
+
+  it('should preserve root when the integrated route prefix is root', () => {
+    ;(window as InjectedPlatformWindow).__MINT_PLATFORM__ = {
+      isIntegrated: true,
+      theme: 'light',
+      plugin: {
+        id: 'root',
+        name: 'Root',
+        version: '1.0.0',
+        route_prefix: '/',
+        api_prefix: '/api',
+      },
+    }
+
+    expect(resolvePluginFrontendBase('./')).toBe('/')
+  })
+})

package/src/__tests__/composables/useApi.test.ts

@@ -1,8 +1,8 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { createPinia, setActivePinia } from 'pinia'
-import type { InternalAxiosRequestConfig } from 'axios'
+import { AxiosError, type AxiosRequestConfig, type InternalAxiosRequestConfig } from 'axios'
 
-import { useApi } from '../../composables/useApi'
+import { AuthenticationRequiredError, useApi } from '../../composables/useApi'
 import { useAuthStore } from '../../stores/auth'
 
 function readAuthorizationHeader(headers: InternalAxiosRequestConfig['headers']): unknown {
@@ -12,6 +12,23 @@ function readAuthorizationHeader(headers: InternalAxiosRequestConfig['headers'])
     ?? bag.authorization
 }
 
+function unauthorizedAdapter(config: AxiosRequestConfig): Promise<never> {
+  const error = new AxiosError(
+    'Unauthorized',
+    AxiosError.ERR_BAD_REQUEST,
+    config as InternalAxiosRequestConfig,
+    undefined,
+    {
+      data: { detail: 'Authentication required' },
+      status: 401,
+      statusText: 'Unauthorized',
+      headers: {},
+      config: config as InternalAxiosRequestConfig,
+    },
+  )
+  return Promise.reject(error)
+}
+
 describe('useApi URL helpers', () => {
   beforeEach(() => {
     setActivePinia(createPinia())
@@ -72,4 +89,61 @@ describe('useApi URL helpers', () => {
     expect(result).toEqual({ ok: true })
     expect(authorization).toBeUndefined()
   })
+
+  it('normalizes authenticated 401 responses and clears the rejected token', async () => {
+    const authStore = useAuthStore()
+    authStore.setToken('expired-token', 3600)
+    const api = useApi({ baseUrl: '/api' })
+
+    const adapter = vi.fn(unauthorizedAdapter)
+    const error = await api.get('/protected', { adapter }).catch((reason: unknown) => reason)
+
+    expect({ attempts: adapter.mock.calls.length, errorType: error?.constructor, token: authStore.token }).toEqual({
+      attempts: 1,
+      errorType: AuthenticationRequiredError,
+      token: null,
+    })
+  })
+
+  it('does not clear auth state for public requests that return 401', async () => {
+    const authStore = useAuthStore()
+    authStore.setToken('still-valid-token', 3600)
+    const api = useApi({ baseUrl: '/api', withAuth: false })
+
+    const error = await api.get('/public', { adapter: unauthorizedAdapter }).catch((reason: unknown) => reason)
+
+    expect({ normalized: error instanceof AuthenticationRequiredError, token: authStore.token }).toEqual({
+      normalized: false,
+      token: 'still-valid-token',
+    })
+  })
+
+  it('does not clear a replacement token after an older request returns 401', async () => {
+    const authStore = useAuthStore()
+    authStore.setToken('rejected-token', 3600)
+    const api = useApi({ baseUrl: '/api' })
+
+    await api.get('/protected', {
+      adapter: async (config) => {
+        authStore.setToken('replacement-token', 3600)
+        return unauthorizedAdapter(config)
+      },
+    }).catch(() => undefined)
+
+    expect(authStore.token).toBe('replacement-token')
+  })
+
+  it('does not clear a token created while an unauthenticated request is in flight', async () => {
+    const authStore = useAuthStore()
+    const api = useApi({ baseUrl: '/api' })
+
+    await api.get('/protected', {
+      adapter: async (config) => {
+        authStore.setToken('new-login-token', 3600)
+        return unauthorizedAdapter(config)
+      },
+    }).catch(() => undefined)
+
+    expect(authStore.token).toBe('new-login-token')
+  })
 })

package/src/__tests__/composables/usePluginClient.test.ts

@@ -18,6 +18,7 @@ import {
   usePluginSettings,
   type PluginContract,
 } from '../../composables/usePluginClient'
+import { AuthenticationRequiredError } from '../../composables/useApi'
 import { useAuthStore } from '../../stores/auth'
 
 const contract: PluginContract = {
@@ -282,6 +283,21 @@ describe('usePluginClient', () => {
     expect(url).toBe('/templates/plate%20map')
   })
 
+  it('builds URLs from FastAPI converted path parameters', () => {
+    const url = buildPluginEndpointUrl(
+      contract,
+      {
+        method: 'get',
+        path: '/raw/{folder}/{filename:path}',
+        pathParams: ['folder', 'filename'],
+      },
+      { folder: 'batch 1', filename: 'sample.mzML' },
+      { includeBaseUrl: false },
+    )
+
+    expect(url).toBe('/raw/batch%201/sample.mzML')
+  })
+
   it('preserves flat scalar query fields when no structured query object is used', () => {
     const url = buildPluginEndpointUrl(
       contract,
@@ -333,6 +349,29 @@ describe('usePluginClient', () => {
     expect(form.get('dryRun')).toBe('false')
   })
 
+  it('uploads generated octet-stream endpoint bodies without multipart conversion', async () => {
+    const body = new Uint8Array([1, 2, 3])
+
+    await uploadPluginEndpoint(
+      contract,
+      {
+        method: 'put',
+        path: '/chunks',
+        hasBody: true,
+        requestContentType: 'application/octet-stream',
+      },
+      body,
+    )
+
+    expect({
+      body: requestBodies[0],
+      contentType: (requestConfigs[0]!.headers as Record<string, unknown>)['Content-Type'],
+    }).toEqual({
+      body,
+      contentType: 'application/octet-stream',
+    })
+  })
+
   it('builds multipart form data from repeated scalar values', () => {
     const form = pluginFormDataFromPayload({
       tags: ['qc', 'plate'],
@@ -371,6 +410,96 @@ describe('usePluginClient', () => {
     expect(requestConfigs[0]!.responseType).toBe('blob')
   })
 
+  it.each([
+    new Blob(['chunk']),
+    new Uint8Array([1, 2, 3]),
+    new Uint8Array([4, 5, 6]).buffer,
+  ])('sends generated octet-stream request bodies without encoding them', async (body) => {
+    const client = createPluginClient(contract, {
+      endpoints: {
+        uploadChunk: {
+          method: 'post',
+          path: '/chunks',
+          hasBody: true,
+          requestContentType: 'application/octet-stream',
+        },
+      },
+    })
+
+    await client.uploadChunk(body)
+
+    expect({
+      body: requestBodies[0],
+      contentType: (requestConfigs[0]!.headers as Record<string, unknown>)['Content-Type'],
+    }).toEqual({
+      body,
+      contentType: 'application/octet-stream',
+    })
+  })
+
+  it('returns generated octet-stream responses as blobs', async () => {
+    const expectedBlob = new Blob(['result'])
+    nextGetData = expectedBlob
+    const client = createPluginClient(contract, {
+      endpoints: {
+        downloadResult: {
+          method: 'get',
+          path: '/result',
+          responseContentType: 'application/octet-stream',
+        },
+      },
+    })
+
+    const result = await client.downloadResult()
+
+    expect({ result, responseType: requestConfigs[0]!.responseType }).toEqual({
+      result: expectedBlob,
+      responseType: 'blob',
+    })
+  })
+
+  it('passes AbortSignal through generated endpoint calls', async () => {
+    const controller = new AbortController()
+    const client = createPluginClient(contract, {
+      endpoints: {
+        health: { method: 'get', path: '/health' },
+      },
+    })
+
+    await client.health({ signal: controller.signal })
+
+    expect(requestConfigs[0]!.signal).toBe(controller.signal)
+  })
+
+  it('encodes generated multipart endpoint bodies as FormData', async () => {
+    const file = new Blob(['csv'])
+    const client = createPluginClient(contract, {
+      endpoints: {
+        uploadFile: {
+          method: 'post',
+          path: '/files',
+          hasBody: true,
+          requestContentType: 'multipart/form-data',
+        },
+      },
+    })
+
+    await client.uploadFile({ file, label: 'sample' })
+
+    const body = requestBodies[0] as FormData
+    expect({
+      isFormData: body instanceof FormData,
+      fileIsBlob: body.get('file') instanceof Blob,
+      label: body.get('label'),
+      contentType: (requestConfigs[0]!.headers as Record<string, unknown>)['Content-Type'],
+    }).toEqual({
+      isFormData: true,
+      fileIsBlob: true,
+      label: 'sample',
+      contentType: undefined,
+    })
+  })
+
   it('triggers browser downloads for existing blobs', () => {
     vi.useFakeTimers()
     const createObjectURL = vi.spyOn(URL, 'createObjectURL').mockReturnValue('blob:test')
@@ -551,6 +680,35 @@ describe('usePluginClient', () => {
     expect(stream.lastEventId.value).toBe('7')
   })
 
+  it('normalizes stream auth failures and does not reconnect rejected requests', async () => {
+    const authStore = useAuthStore()
+    authStore.setToken('expired-stream-token', 3600)
+    const onError = vi.fn()
+    const fetchMock = vi.fn(async () => new Response(null, { status: 401 }))
+    vi.stubGlobal('fetch', fetchMock)
+
+    const stream = usePluginEventStream(
+      contract,
+      { method: 'get', path: '/downloads/events' },
+      { reconnectDelayMs: 1, onError },
+    )
+
+    await vi.waitFor(() => expect(onError).toHaveBeenCalledOnce())
+    await new Promise((resolve) => setTimeout(resolve, 10))
+
+    expect({
+      attempts: fetchMock.mock.calls.length,
+      errorType: onError.mock.calls[0]![0]?.constructor,
+      message: stream.error.value,
+      token: authStore.token,
+    }).toEqual({
+      attempts: 1,
+      errorType: AuthenticationRequiredError,
+      message: 'Authentication required. Please sign in again.',
+      token: null,
+    })
+  })
+
   it('parses generated typed event streams as JSON by default', async () => {
     const onMessage = vi.fn()
     const streamBody = new ReadableStream({

package/src/composables/index.ts

@@ -1,9 +1,15 @@
-export { useApi, type ApiClientOptions } from './useApi'
+export {
+  AuthenticationRequiredError,
+  useApi,
+  type ApiClientOptions,
+  type UseApiReturn,
+} from './useApi'
 export { useAuth } from './useAuth'
 export { usePasskey } from './usePasskey'
 export { useTheme } from './useTheme'
 export { useToast } from './useToast'
 export { usePlatformContext } from './usePlatformContext'
+export { resolvePluginFrontendBase } from './pluginFrontendBase'
 export {
   useForm,
   type ValidationRule,
@@ -452,6 +458,7 @@ export {
   type DownloadBlobOptions,
   type DownloadPluginEndpointOptions,
   type PluginContract,
+  type PluginClientRequestOptions,
   type PluginEndpointContract,
   type PluginEndpointDefinition,
   type PluginHttpMethod,

package/src/composables/pluginEndpointBuilder.ts

@@ -30,6 +30,17 @@ function endpointParamFieldName(param: PluginEndpointParamDefinition): string {
   return typeof param === 'string' ? param : param.fieldName ?? param.name
 }
 
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+function replacePathParam(path: string, name: string, encoded: string): string {
+  const escapedName = escapeRegExp(name)
+  return path
+    .replace(new RegExp(`\\{${escapedName}(?::[^{}]+)?\\}`, 'g'), () => encoded)
+    .replace(new RegExp(`:${escapedName}(?=/|$)`, 'g'), () => encoded)
+}
+
 /** Resolve the runtime plugin API base URL from env, explicit options, platform injection, or contract metadata. */
 export function resolvePluginBaseUrl(contract: PluginContract, explicitBaseUrl?: string): string {
   const envPrefix = (import.meta.env?.VITE_API_PREFIX as string | undefined) || undefined
@@ -59,11 +70,9 @@ function encodePath(
       throw new Error(`[MINT SDK] Missing path parameter '${fieldName}' for plugin endpoint ${path}`)
     }
     const encoded = encodeURIComponent(String(value))
-    nextPath = nextPath.replace(`{${name}}`, encoded)
-    nextPath = nextPath.replace(`:${name}`, encoded)
+    nextPath = replacePathParam(nextPath, name, encoded)
     if (fieldName !== name) {
-      nextPath = nextPath.replace(`{${fieldName}}`, encoded)
-      nextPath = nextPath.replace(`:${fieldName}`, encoded)
+      nextPath = replacePathParam(nextPath, fieldName, encoded)
     }
   }
   return nextPath

package/src/composables/pluginFrontendBase.ts

@@ -0,0 +1,22 @@
+import { getInjectedPlatformContext } from './platformContextHelpers'
+
+function normalizePluginRoutePrefix(prefix: string | undefined): string | undefined {
+  const candidate = prefix?.trim()
+  if (!candidate) return undefined
+
+  const path = candidate.split('/').filter(Boolean).join('/')
+  return path ? `/${path}/` : '/'
+}
+
+/**
+ * Resolve the Vue Router base for a plugin frontend.
+ *
+ * Integrated plugins use the platform-injected mount prefix. Standalone and
+ * development builds retain the caller's Vite base unchanged.
+ */
+export function resolvePluginFrontendBase(fallbackBase: string = '/'): string {
+  const context = getInjectedPlatformContext()
+  if (!context?.isIntegrated) return fallbackBase
+
+  return normalizePluginRoutePrefix(context.plugin?.route_prefix) ?? fallbackBase
+}

package/src/composables/useApi.ts

@@ -7,10 +7,12 @@ let interceptorAttached = false
 
 interface MintAxiosRequestConfig extends AxiosRequestConfig {
   _mintSkipAuth?: boolean
+  _mintAuthToken?: string
 }
 
 interface MintInternalAxiosRequestConfig extends InternalAxiosRequestConfig {
   _mintSkipAuth?: boolean
+  _mintAuthToken?: string
 }
 
 type MutableHeaders = Record<string, unknown> & {
@@ -92,6 +94,37 @@ function deleteAuthorizationHeader(headers: AxiosRequestConfig['headers']): void
   }
 }
 
+function getAuthorizationHeader(headers: AxiosRequestConfig['headers']): unknown {
+  const bag = asMutableHeaders(headers) as (MutableHeaders & { get?: (header: string) => unknown }) | null
+  if (!bag) return undefined
+  if (typeof bag.get === 'function') return bag.get('Authorization')
+  const key = Object.keys(bag).find((candidate) => candidate.toLowerCase() === 'authorization')
+  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'
+  }
+}
+
+/** @internal Convert a rejected authenticated request into the SDK's public auth error. */
+export function authenticationRequiredError(
+  cause: unknown,
+  rejectedToken?: string,
+): AuthenticationRequiredError {
+  const currentAuthStore = useAuthStore()
+  if (rejectedToken && currentAuthStore.token === rejectedToken) {
+    currentAuthStore.clearToken()
+  }
+  return new AuthenticationRequiredError(cause)
+}
+
 function getApiClient(): AxiosInstance {
   if (!apiClientInstance) {
     apiClientInstance = axios.create({
@@ -138,7 +171,6 @@ export function useApi(options: ApiClientOptions = {}): UseApiReturn {
     apiClient.interceptors.request.use((config) => {
       const request = config as MintInternalAxiosRequestConfig
       if (request._mintSkipAuth) {
-        delete request._mintSkipAuth
         deleteAuthorizationHeader(request.headers)
         return request
       }
@@ -147,8 +179,23 @@ export function useApi(options: ApiClientOptions = {}): UseApiReturn {
       if (currentAuthStore.token && config.headers && !hasAuthorizationHeader(config.headers)) {
         setAuthorizationHeader(config.headers, `Bearer ${currentAuthStore.token}`)
       }
+      if (getAuthorizationHeader(config.headers) === `Bearer ${currentAuthStore.token}`) {
+        request._mintAuthToken = currentAuthStore.token ?? undefined
+      }
       return config
     })
+    apiClient.interceptors.response.use(
+      (response) => response,
+      (error: unknown) => {
+        if (axios.isAxiosError(error) && error.response?.status === 401) {
+          const request = error.config as MintInternalAxiosRequestConfig | undefined
+          if (request?._mintSkipAuth !== true) {
+            return Promise.reject(authenticationRequiredError(error, request?._mintAuthToken))
+          }
+        }
+        return Promise.reject(error)
+      },
+    )
     interceptorAttached = true
   }