@morscherlab/mint-sdk 1.0.0-rc.4 → 1.0.0-rc.6

package/src/composables/pluginEndpointBuilder.ts

@@ -0,0 +1,203 @@
+import {
+  getInjectedPlatformContext,
+  resolveCurrentExperimentId,
+} from './platformContextHelpers'
+import type {
+  BuildPluginEndpointUrlOptions,
+  PluginContract,
+  PluginEndpointDefinition,
+  PluginEndpointParamDefinition,
+} from './usePluginClient'
+
+function normalizeApiBaseUrl(baseUrl: string | undefined): string | undefined {
+  if (!baseUrl) return undefined
+  return baseUrl.length > 1 ? baseUrl.replace(/\/+$/, '') : baseUrl
+}
+
+function normalizeApiPrefix(prefix: string | undefined): string | undefined {
+  if (!prefix) return undefined
+  if (prefix.startsWith('/api/')) return normalizeApiBaseUrl(prefix)
+  if (prefix === '/api') return prefix
+  if (prefix.startsWith('/')) return normalizeApiBaseUrl(`/api${prefix}`)
+  return normalizeApiBaseUrl(`/api/${prefix}`)
+}
+
+/** 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
+  if (envPrefix) return normalizeApiBaseUrl(envPrefix) ?? envPrefix
+  if (explicitBaseUrl) return normalizeApiBaseUrl(explicitBaseUrl) ?? explicitBaseUrl
+
+  const injected = getInjectedPlatformContext()
+  const platformPrefix =
+    normalizeApiBaseUrl(injected?.plugin?.api_prefix) ||
+    normalizeApiPrefix(injected?.plugin?.route_prefix)
+  if (platformPrefix) return platformPrefix
+
+  return normalizeApiBaseUrl(contract.plugin.apiPrefix) || '/api'
+}
+
+function encodePath(path: string, payload: Record<string, unknown>, pathParams: string[]): string {
+  let nextPath = path
+  for (const param of pathParams) {
+    const value = payload[param]
+    if (value === undefined || value === null) {
+      throw new Error(`[MINT SDK] Missing path parameter '${param}' for plugin endpoint ${path}`)
+    }
+    nextPath = nextPath.replace(`{${param}}`, encodeURIComponent(String(value)))
+    nextPath = nextPath.replace(`:${param}`, encodeURIComponent(String(value)))
+  }
+  return nextPath
+}
+
+function withDefaultPathParams(
+  payload: Record<string, unknown>,
+  pathParams: string[],
+): Record<string, unknown> {
+  if (!pathParams.length) return payload
+  const nextPayload = { ...payload }
+  for (const param of pathParams) {
+    if (nextPayload[param] !== undefined && nextPayload[param] !== null) continue
+    if (isExperimentPathParam(param)) {
+      const experimentId = resolveCurrentExperimentId()
+      if (experimentId !== undefined) {
+        nextPayload[param] = experimentId
+      }
+    }
+  }
+  return nextPayload
+}
+
+function isExperimentPathParam(param: string): boolean {
+  return param === 'experimentId' || param === 'experiment_id'
+}
+
+function withoutPathParams(payload: Record<string, unknown>, pathParams: string[]) {
+  const copy = { ...payload }
+  for (const param of pathParams) {
+    delete copy[param]
+  }
+  return copy
+}
+
+function queryParamsFromPayload(
+  payload: Record<string, unknown>,
+  pathParams: string[],
+  queryParams?: PluginEndpointParamDefinition[],
+  endpointPath?: string,
+  includeUnspecifiedParams = false,
+) {
+  if (!queryParams?.length) {
+    return includeUnspecifiedParams ? withoutPathParams(payload, pathParams) : {}
+  }
+
+  const query: Record<string, unknown> = {}
+  for (const param of queryParams) {
+    const name = typeof param === 'string' ? param : param.name
+    const fieldName = typeof param === 'string' ? param : param.fieldName ?? param.name
+    const required = typeof param !== 'string' && param.required === true
+    const value = payload[fieldName]
+    if (value === undefined || value === null) {
+      if (required) {
+        throw new Error(
+          `[MINT SDK] Missing query parameter '${fieldName}' for plugin endpoint ${endpointPath ?? ''}`,
+        )
+      }
+      continue
+    }
+    query[name] = value
+  }
+  return query
+}
+
+export function hasKeys(value: Record<string, unknown>): boolean {
+  return Object.keys(value).length > 0
+}
+
+export function requestBodyFromPayload(
+  payload: unknown,
+  requestPayload: Record<string, unknown>,
+  endpoint: PluginEndpointDefinition,
+): unknown {
+  if (!endpoint.hasBody) return undefined
+  const body = endpoint.pathParams?.length || endpoint.queryParams?.length
+    ? requestPayload.body
+    : payload
+  if (body === undefined || body === null) {
+    throw new Error(`[MINT SDK] Missing request body for plugin endpoint ${endpoint.path}`)
+  }
+  return body
+}
+
+export function pluginEndpointRequestParts(
+  contract: PluginContract,
+  endpoint: PluginEndpointDefinition,
+  payload?: unknown,
+  explicitBaseUrl?: string,
+) {
+  const payloadObject =
+    payload && typeof payload === 'object' && !Array.isArray(payload)
+      ? payload as Record<string, unknown>
+      : {}
+  const pathParams = endpoint.pathParams ?? []
+  const requestPayload = withDefaultPathParams(payloadObject, pathParams)
+  const path = encodePath(endpoint.path, requestPayload, pathParams)
+  const query = queryParamsFromPayload(
+    requestPayload,
+    pathParams,
+    endpoint.queryParams,
+    endpoint.path,
+    endpoint.method === 'get',
+  )
+
+  return {
+    baseUrl: resolvePluginBaseUrl(contract, explicitBaseUrl),
+    path,
+    query,
+    requestPayload,
+  }
+}
+
+function appendQueryValue(params: URLSearchParams, key: string, value: unknown): void {
+  if (value === undefined || value === null) return
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      appendQueryValue(params, key, item)
+    }
+    return
+  }
+  if (typeof value === 'object') {
+    params.append(key, JSON.stringify(value))
+    return
+  }
+  params.append(key, String(value))
+}
+
+function queryString(query: Record<string, unknown>): string {
+  const params = new URLSearchParams()
+  for (const [key, value] of Object.entries(query)) {
+    appendQueryValue(params, key, value)
+  }
+  const serialized = params.toString()
+  return serialized ? `?${serialized}` : ''
+}
+
+function joinBaseUrl(baseUrl: string, path: string): string {
+  if (!baseUrl) return path
+  const normalizedBase = baseUrl.endsWith('/') ? baseUrl.slice(0, -1) : baseUrl
+  const normalizedPath = path.startsWith('/') ? path : `/${path}`
+  return `${normalizedBase}${normalizedPath}`
+}
+
+/** Build the concrete URL for a generated plugin endpoint without making a request. */
+export function buildPluginEndpointUrl(
+  contract: PluginContract,
+  endpoint: PluginEndpointDefinition,
+  payload?: unknown,
+  options: BuildPluginEndpointUrlOptions = {},
+): string {
+  const parts = pluginEndpointRequestParts(contract, endpoint, payload, options.baseUrl)
+  const pathWithQuery = `${parts.path}${queryString(parts.query)}`
+  if (options.includeBaseUrl === false) return pathWithQuery
+  return joinBaseUrl(parts.baseUrl, pathWithQuery)
+}

package/src/composables/protocolTemplateCatalog.ts

@@ -0,0 +1,325 @@
+import type { ProtocolStepType } from '../types'
+
+// Parameter definition for step templates
+export interface ParameterDefinition {
+  key: string
+  label: string
+  type: 'number' | 'text' | 'select' | 'concentration' | 'temperature' | 'duration' | 'reagent'
+  unit?: string
+  options?: Array<{ value: string; label: string }>
+  required?: boolean
+  default?: unknown
+  min?: number
+  max?: number
+  placeholder?: string
+}
+
+// Step template definition
+export interface StepTemplate {
+  id: string
+  type: ProtocolStepType
+  name: string
+  description?: string
+  defaultDuration?: number
+  parameters: ParameterDefinition[]
+  isBuiltIn?: boolean
+}
+
+export const BUILT_IN_PROTOCOL_TEMPLATES: StepTemplate[] = [
+  {
+    id: 'builtin-incubation',
+    type: 'incubation',
+    name: 'Incubation',
+    description: 'Incubate samples at specified conditions',
+    defaultDuration: 60,
+    isBuiltIn: true,
+    parameters: [
+      {
+        key: 'temperature',
+        label: 'Temperature',
+        type: 'temperature',
+        unit: '°C',
+        required: true,
+        default: 37,
+        min: -80,
+        max: 100,
+      },
+      {
+        key: 'duration',
+        label: 'Duration',
+        type: 'duration',
+        unit: 'hours',
+        required: true,
+        default: 24,
+        min: 0,
+      },
+      {
+        key: 'co2',
+        label: 'CO2',
+        type: 'number',
+        unit: '%',
+        required: false,
+        default: 5,
+        min: 0,
+        max: 100,
+      },
+      {
+        key: 'humidity',
+        label: 'Humidity',
+        type: 'number',
+        unit: '%',
+        required: false,
+        default: 95,
+        min: 0,
+        max: 100,
+      },
+    ],
+  },
+  {
+    id: 'builtin-wash',
+    type: 'wash',
+    name: 'Wash',
+    description: 'Wash samples with buffer',
+    defaultDuration: 5,
+    isBuiltIn: true,
+    parameters: [
+      {
+        key: 'buffer',
+        label: 'Buffer',
+        type: 'select',
+        required: true,
+        default: 'PBS',
+        options: [
+          { value: 'PBS', label: 'PBS' },
+          { value: 'PBST', label: 'PBST' },
+          { value: 'TBS', label: 'TBS' },
+          { value: 'TBST', label: 'TBST' },
+          { value: 'Water', label: 'Water' },
+          { value: 'Other', label: 'Other' },
+        ],
+      },
+      {
+        key: 'volume',
+        label: 'Volume',
+        type: 'number',
+        unit: 'µL',
+        required: true,
+        default: 200,
+        min: 0,
+      },
+      {
+        key: 'cycles',
+        label: 'Wash Cycles',
+        type: 'number',
+        required: true,
+        default: 3,
+        min: 1,
+        max: 10,
+      },
+    ],
+  },
+  {
+    id: 'builtin-addition',
+    type: 'addition',
+    name: 'Addition',
+    description: 'Add reagent or compound to samples',
+    defaultDuration: 5,
+    isBuiltIn: true,
+    parameters: [
+      {
+        key: 'reagent',
+        label: 'Reagent',
+        type: 'text',
+        required: true,
+        placeholder: 'Enter reagent name',
+      },
+      {
+        key: 'volume',
+        label: 'Volume',
+        type: 'number',
+        unit: 'µL',
+        required: true,
+        default: 100,
+        min: 0,
+      },
+      {
+        key: 'concentration',
+        label: 'Concentration',
+        type: 'concentration',
+        required: false,
+      },
+    ],
+  },
+  {
+    id: 'builtin-measurement',
+    type: 'measurement',
+    name: 'Measurement',
+    description: 'Take measurements using specified instrument',
+    defaultDuration: 15,
+    isBuiltIn: true,
+    parameters: [
+      {
+        key: 'instrument',
+        label: 'Instrument',
+        type: 'select',
+        required: true,
+        options: [
+          { value: 'plate_reader', label: 'Plate Reader' },
+          { value: 'microscope', label: 'Microscope' },
+          { value: 'flow_cytometer', label: 'Flow Cytometer' },
+          { value: 'spectrophotometer', label: 'Spectrophotometer' },
+          { value: 'other', label: 'Other' },
+        ],
+      },
+      {
+        key: 'readout',
+        label: 'Readout Type',
+        type: 'text',
+        required: false,
+        placeholder: 'e.g., Absorbance 450nm',
+      },
+      {
+        key: 'notes',
+        label: 'Parameters',
+        type: 'text',
+        required: false,
+        placeholder: 'Additional parameters',
+      },
+    ],
+  },
+  {
+    id: 'builtin-centrifuge',
+    type: 'centrifuge',
+    name: 'Centrifuge',
+    description: 'Centrifuge samples',
+    defaultDuration: 10,
+    isBuiltIn: true,
+    parameters: [
+      {
+        key: 'speed',
+        label: 'Speed',
+        type: 'number',
+        unit: 'RPM',
+        required: true,
+        default: 1000,
+        min: 100,
+        max: 20000,
+      },
+      {
+        key: 'duration',
+        label: 'Duration',
+        type: 'number',
+        unit: 'min',
+        required: true,
+        default: 5,
+        min: 1,
+      },
+      {
+        key: 'temperature',
+        label: 'Temperature',
+        type: 'temperature',
+        unit: '°C',
+        required: false,
+        default: 4,
+        min: -10,
+        max: 40,
+      },
+    ],
+  },
+  {
+    id: 'builtin-transfer',
+    type: 'transfer',
+    name: 'Transfer',
+    description: 'Transfer samples between containers',
+    defaultDuration: 10,
+    isBuiltIn: true,
+    parameters: [
+      {
+        key: 'source',
+        label: 'Source',
+        type: 'text',
+        required: true,
+        placeholder: 'Source container',
+      },
+      {
+        key: 'destination',
+        label: 'Destination',
+        type: 'text',
+        required: true,
+        placeholder: 'Destination container',
+      },
+      {
+        key: 'volume',
+        label: 'Volume',
+        type: 'number',
+        unit: 'µL',
+        required: true,
+        default: 100,
+        min: 0,
+      },
+    ],
+  },
+  {
+    id: 'builtin-mix',
+    type: 'mix',
+    name: 'Mix',
+    description: 'Mix samples',
+    defaultDuration: 5,
+    isBuiltIn: true,
+    parameters: [
+      {
+        key: 'method',
+        label: 'Method',
+        type: 'select',
+        required: true,
+        default: 'pipette',
+        options: [
+          { value: 'pipette', label: 'Pipette mixing' },
+          { value: 'vortex', label: 'Vortex' },
+          { value: 'shaker', label: 'Orbital shaker' },
+          { value: 'inversion', label: 'Inversion' },
+        ],
+      },
+      {
+        key: 'duration',
+        label: 'Duration',
+        type: 'number',
+        unit: 'sec',
+        required: false,
+        default: 30,
+        min: 1,
+      },
+      {
+        key: 'speed',
+        label: 'Speed/Intensity',
+        type: 'text',
+        required: false,
+        placeholder: 'e.g., 300 RPM',
+      },
+    ],
+  },
+  {
+    id: 'builtin-custom',
+    type: 'custom',
+    name: 'Custom Step',
+    description: 'Custom protocol step',
+    defaultDuration: 15,
+    isBuiltIn: true,
+    parameters: [
+      {
+        key: 'description',
+        label: 'Description',
+        type: 'text',
+        required: true,
+        placeholder: 'Describe the step',
+      },
+      {
+        key: 'notes',
+        label: 'Notes',
+        type: 'text',
+        required: false,
+        placeholder: 'Additional notes',
+      },
+    ],
+  },
+]