@morscherlab/mint-sdk 1.0.62 → 1.0.63

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@morscherlab/mint-sdk",
-  "version": "1.0.62",
+  "version": "1.0.63",
   "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/analysisArtifactTarget.test.ts

@@ -0,0 +1,77 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+import {
+  buildAnalysisArtifactTargetQuery,
+  parseAnalysisArtifactTarget,
+} from '../../composables/analysisArtifactTarget'
+import {
+  currentExperimentIdFromUrl,
+  resolveCurrentPluginId,
+} from '../../composables/platformContextHelpers'
+
+describe('analysis artifact target', () => {
+  afterEach(() => {
+    delete (window as unknown as { __MINT_PLATFORM__?: unknown }).__MINT_PLATFORM__
+    vi.unstubAllGlobals()
+  })
+
+  it('should resolve the canonical injected plugin id', () => {
+    ;(window as unknown as { __MINT_PLATFORM__: unknown }).__MINT_PLATFORM__ = {
+      isIntegrated: true,
+      plugin: { id: 'LEAF', name: 'Leaf UI' },
+      theme: 'system',
+    }
+
+    expect(resolveCurrentPluginId()).toBe('LEAF')
+  })
+
+  it('should tolerate a host that provides a partial location object', () => {
+    vi.stubGlobal('window', {
+      location: { search: '' },
+    })
+
+    expect(currentExperimentIdFromUrl()).toBeUndefined()
+  })
+
+  it('should build the canonical readable query when an artifact id hint is present', () => {
+    const query = buildAnalysisArtifactTargetQuery({
+      experimentId: 66,
+      artifactPluginId: 'LEAF',
+      artifactKey: 'exp316_260703_ys_rna_ide_scr',
+      artifactId: 206,
+    })
+
+    expect(query.toString()).toBe(
+      'experiment_id=66&artifact_plugin_id=LEAF'
+      + '&artifact_key=exp316_260703_ys_rna_ide_scr&artifact_id=206',
+    )
+  })
+
+  it('should parse the canonical identity without requiring an artifact id hint', () => {
+    const target = parseAnalysisArtifactTarget(new URLSearchParams(
+      'experiment_id=66&artifact_plugin_id=LEAF&artifact_key=result',
+    ))
+
+    expect(target).toEqual({
+      experimentId: 66,
+      artifactPluginId: 'LEAF',
+      artifactKey: 'result',
+    })
+  })
+
+  it('should reject an incomplete target instead of guessing another artifact', () => {
+    const target = parseAnalysisArtifactTarget(new URLSearchParams(
+      'experiment_id=66&artifact_key=result',
+    ))
+
+    expect(target).toBeNull()
+  })
+
+  it('should reject non-positive numeric identifiers', () => {
+    const target = parseAnalysisArtifactTarget(new URLSearchParams(
+      'experiment_id=0&artifact_plugin_id=LEAF&artifact_key=result&artifact_id=-1',
+    ))
+
+    expect(target).toBeNull()
+  })
+})

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

@@ -19,7 +19,10 @@ vi.mock('../../composables/useApi', () => ({
 }))
 
 import { useAnalysisArtifacts } from '../../composables/useAnalysisArtifacts'
-import type { AnalysisArtifactSummary } from '../../types/analysisArtifactTypes'
+import type {
+  AnalysisArtifactDetail,
+  AnalysisArtifactSummary,
+} from '../../types/analysisArtifactTypes'
 
 // ---------------------------------------------------------------------------
 // Fixtures
@@ -177,6 +180,76 @@ describe('useAnalysisArtifacts', () => {
     })
   })
 
+  describe('resolveTarget', () => {
+    it('should resolve the exact stable identity when the numeric hint is stale', async () => {
+      const detail = {
+        ...makeArtifact({
+          id: 2,
+          experiment_id: 42,
+          plugin_id: 'plugin-b',
+          artifact_key: 'peaks',
+        }),
+        result: { schema_version: 'mint.analysis_file.v1' },
+        tree: [],
+        summary: null,
+      } satisfies AnalysisArtifactDetail
+      mockGet
+        .mockResolvedValueOnce({ artifacts: ARTIFACTS })
+        .mockResolvedValueOnce(detail)
+      const { resolveTarget } = setup()
+
+      const resolved = await resolveTarget({
+        experimentId: 42,
+        artifactPluginId: 'plugin-b',
+        artifactKey: 'peaks',
+        artifactId: 999,
+      })
+
+      expect({
+        resolvedId: resolved?.id,
+        detailPath: mockGet.mock.calls[1]?.[0],
+      }).toEqual({
+        resolvedId: 2,
+        detailPath: '/experiments/42/analysis-artifacts/2',
+      })
+    })
+
+    it('should fail explicitly when the stable identity is not available', async () => {
+      const { resolveTarget, error } = setup()
+
+      const resolved = await resolveTarget({
+        experimentId: 42,
+        artifactPluginId: 'LEAF',
+        artifactKey: 'missing',
+      })
+
+      expect({ resolved, error: error.value }).toEqual({
+        resolved: null,
+        error: 'Analysis artifact LEAF/missing is not available.',
+      })
+    })
+
+    it('should reject a target from another experiment before making a request', async () => {
+      const { resolveTarget, error } = setup()
+
+      const resolved = await resolveTarget({
+        experimentId: 66,
+        artifactPluginId: 'LEAF',
+        artifactKey: 'result',
+      })
+
+      expect({
+        resolved,
+        error: error.value,
+        requests: mockGet.mock.calls,
+      }).toEqual({
+        resolved: null,
+        error: 'Analysis artifact target belongs to experiment 66, not 42.',
+        requests: [],
+      })
+    })
+  })
+
   // -------------------------------------------------------------------------
   // experiment id resolution
   // -------------------------------------------------------------------------

package/src/composables/analysisArtifactTarget.ts

@@ -0,0 +1,53 @@
+import type { AnalysisArtifactTarget } from '../types/analysisArtifactTypes'
+
+const EXPERIMENT_ID = 'experiment_id'
+const ARTIFACT_PLUGIN_ID = 'artifact_plugin_id'
+const ARTIFACT_KEY = 'artifact_key'
+const ARTIFACT_ID = 'artifact_id'
+
+function parsePositiveInteger(value: string | null): number | undefined {
+  if (value === null || !/^\d+$/.test(value)) return undefined
+  const parsed = Number(value)
+  return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : undefined
+}
+
+/** Build the canonical query used to open one analysis artifact in a plugin. */
+export function buildAnalysisArtifactTargetQuery(
+  target: AnalysisArtifactTarget,
+): URLSearchParams {
+  const query = new URLSearchParams()
+  query.set(EXPERIMENT_ID, String(target.experimentId))
+  query.set(ARTIFACT_PLUGIN_ID, target.artifactPluginId)
+  query.set(ARTIFACT_KEY, target.artifactKey)
+  if (target.artifactId !== undefined) {
+    query.set(ARTIFACT_ID, String(target.artifactId))
+  }
+  return query
+}
+
+/** Parse a complete canonical target. Incomplete or invalid input is not guessed. */
+export function parseAnalysisArtifactTarget(
+  query: URLSearchParams,
+): AnalysisArtifactTarget | null {
+  const experimentId = parsePositiveInteger(query.get(EXPERIMENT_ID))
+  const artifactPluginId = query.get(ARTIFACT_PLUGIN_ID)?.trim()
+  const artifactKey = query.get(ARTIFACT_KEY)?.trim()
+  const rawArtifactId = query.get(ARTIFACT_ID)
+  const artifactId = parsePositiveInteger(rawArtifactId)
+
+  if (
+    experimentId === undefined
+    || !artifactPluginId
+    || !artifactKey
+    || (rawArtifactId !== null && artifactId === undefined)
+  ) {
+    return null
+  }
+
+  return {
+    experimentId,
+    artifactPluginId,
+    artifactKey,
+    ...(artifactId === undefined ? {} : { artifactId }),
+  }
+}

package/src/composables/index.ts

@@ -147,6 +147,11 @@ export {
   type UseAnalysisArtifactsOptions,
   type UseAnalysisArtifactsReturn,
 } from './useAnalysisArtifacts'
+export {
+  buildAnalysisArtifactTargetQuery,
+  parseAnalysisArtifactTarget,
+} from './analysisArtifactTarget'
+export { resolveCurrentPluginId } from './platformContextHelpers'
 export {
   formatExperimentDate,
   formatExperimentStatus,

package/src/composables/platformContextHelpers.ts

@@ -12,6 +12,12 @@ export function getInjectedPlatformContext(): PlatformContext | undefined {
   return (window as unknown as { __MINT_PLATFORM__?: PlatformContext }).__MINT_PLATFORM__
 }
 
+/** Return the platform's canonical plugin identity for the mounted frontend. */
+export function resolveCurrentPluginId(): string | undefined {
+  const pluginId = getInjectedPlatformContext()?.plugin?.id
+  return typeof pluginId === 'string' && pluginId ? pluginId : undefined
+}
+
 export function getInjectedExperimentContext(): ExperimentAwarePlatformContext | undefined {
   return getInjectedPlatformContext() as ExperimentAwarePlatformContext | undefined
 }
@@ -38,10 +44,11 @@ export function currentExperimentIdFromContext(
 
 export function currentExperimentIdFromUrl(): number | undefined {
   if (typeof window === 'undefined') return undefined
-  const params = new URLSearchParams(window.location.search)
+  const location = window.location
+  const params = new URLSearchParams(location?.search ?? '')
   return parseExperimentId(params.get('experimentId') ?? params.get('experiment_id'))
-    ?? experimentIdFromPath(window.location.pathname)
-    ?? experimentIdFromPath(window.location.hash.replace(/^#\/?/, '/'))
+    ?? experimentIdFromPath(location?.pathname ?? '')
+    ?? experimentIdFromPath((location?.hash ?? '').replace(/^#\/?/, '/'))
 }
 
 export function resolveCurrentExperimentId(

package/src/composables/useAnalysisArtifacts.ts

@@ -19,6 +19,7 @@ import type {
   AnalysisArtifactMetadataUpdate,
   AnalysisArtifactStatusFilter,
   AnalysisArtifactSummary,
+  AnalysisArtifactTarget,
 } from '../types/analysisArtifactTypes'
 
 export { ANALYSIS_FILE_ARTIFACT_SCHEMA } from '../types/analysisArtifactTypes'
@@ -67,6 +68,8 @@ export interface UseAnalysisArtifactsReturn {
   refresh: () => Promise<AnalysisArtifactSummary[]>
   /** Fetch one artifact with its result payload; null when it fails or is superseded. */
   getDetail: (artifactId: number) => Promise<AnalysisArtifactDetail | null>
+  /** Resolve and fetch the exact stable artifact identity. */
+  resolveTarget: (target: AnalysisArtifactTarget) => Promise<AnalysisArtifactDetail | null>
   /** Update display_name and/or note; resolves to the updated summary or null. */
   updateMetadata: (
     artifactId: number,
@@ -206,6 +209,50 @@ export function useAnalysisArtifacts(
     }
   }
 
+  async function resolveTarget(
+    target: AnalysisArtifactTarget,
+  ): Promise<AnalysisArtifactDetail | null> {
+    const experimentId = currentExperimentId.value
+    if (experimentId !== target.experimentId) {
+      request.setError(
+        `Analysis artifact target belongs to experiment ${target.experimentId}, not `
+        + `${experimentId ?? 'the current selection'}.`,
+      )
+      return null
+    }
+
+    const available = await list()
+    const summary = available.find((artifact) => (
+      artifact.plugin_id === target.artifactPluginId
+      && artifact.artifact_key === target.artifactKey
+      && artifact.status === 'active'
+    ))
+    if (!summary) {
+      request.setError(
+        `Analysis artifact ${target.artifactPluginId}/${target.artifactKey} is not available.`,
+      )
+      return null
+    }
+
+    const detail = await getDetail(summary.id)
+    if (
+      detail
+      && (
+        detail.experiment_id !== target.experimentId
+        || detail.plugin_id !== target.artifactPluginId
+        || detail.artifact_key !== target.artifactKey
+      )
+    ) {
+      selectedDetail.value = null
+      request.setError(
+        `Analysis artifact ${target.artifactPluginId}/${target.artifactKey} did not `
+        + 'match the requested identity.',
+      )
+      return null
+    }
+    return detail
+  }
+
   async function mutate(
     action: string,
     operation: (experimentId: number) => Promise<AnalysisArtifactSummary>,
@@ -296,6 +343,7 @@ export function useAnalysisArtifacts(
     list,
     refresh: list,
     getDetail,
+    resolveTarget,
     updateMetadata,
     archive,
     restore,

package/src/types/analysisArtifactTypes.ts

@@ -38,6 +38,15 @@ export interface AnalysisArtifactListResponse {
   artifacts: AnalysisArtifactSummary[]
 }
 
+/** Stable identity used when one plugin opens another plugin's artifact. */
+export interface AnalysisArtifactTarget {
+  experimentId: number
+  artifactPluginId: string
+  artifactKey: string
+  /** Optional lookup hint. The stable identity remains the three fields above. */
+  artifactId?: number
+}
+
 /** Body of PATCH /experiments/{id}/analysis-artifacts/{artifactId}. */
 export interface AnalysisArtifactMetadataUpdate {
   display_name?: string

package/src/types/index.ts

@@ -182,6 +182,7 @@ export type {
   AnalysisArtifactSummary,
   AnalysisArtifactDetail,
   AnalysisArtifactListResponse,
+  AnalysisArtifactTarget,
   AnalysisArtifactMetadataUpdate,
   ArtifactSaveMode,
   ArtifactFileSource,