@morscherlab/mint-sdk 1.2.0-beta.3 → 1.2.0-beta.5

package/src/types/analysisArtifactTypes.ts

@@ -0,0 +1,176 @@
+import type { TreeNode } from './componentLabTypes'
+import type { SummaryData } from './componentWorkflowTypes'
+
+/** Result schema identifier for file-backed analysis artifacts. */
+export const ANALYSIS_FILE_ARTIFACT_SCHEMA = 'mint.analysis_file.v1'
+
+/** Known artifact lifecycle states; kept open for forward compatibility. */
+export type AnalysisArtifactStatus = 'active' | 'archived' | (string & {})
+
+/** Status filter vocabulary for artifact lists. */
+export type AnalysisArtifactStatusFilter = 'active' | 'archived' | 'all'
+
+/** Summary row returned by GET /experiments/{id}/analysis-artifacts. */
+export interface AnalysisArtifactSummary {
+  id: number
+  experiment_id: number
+  plugin_id: string
+  artifact_key: string
+  display_name: string
+  note?: string | null
+  status: AnalysisArtifactStatus
+  result_keys: string[]
+  created_at?: string | null
+  updated_at?: string | null
+  archived_at?: string | null
+  archived_by?: number | null
+}
+
+/** Full artifact returned by GET /experiments/{id}/analysis-artifacts/{artifactId}. */
+export interface AnalysisArtifactDetail extends AnalysisArtifactSummary {
+  result: Record<string, unknown>
+  tree: TreeNode[]
+  summary: SummaryData | null
+}
+
+/** Response of GET /experiments/{id}/analysis-artifacts. */
+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
+  /** undefined = keep, string = set, null = clear. */
+  note?: string | null
+}
+
+/** How a save payload should be applied by the plugin backend. */
+export type ArtifactSaveMode = 'create' | 'upsert' | 'update'
+
+/** Where file content comes from when a plugin uses ArtifactSaveDialog. */
+export type ArtifactFileSource = 'upload' | 'handler'
+
+interface ArtifactSavePayloadBase {
+  experimentId: number
+  artifactKey: string
+}
+
+/**
+ * JSON artifact save — handler maps to save_analysis_artifact, which upserts by key.
+ * That call only assigns display_name/note when they are provided, and cannot clear
+ * either; use the metadata PATCH (useAnalysisArtifacts.updateMetadata) for that.
+ */
+export interface JsonArtifactSavePayload extends ArtifactSavePayloadBase {
+  kind: 'json'
+  mode: 'create' | 'upsert'
+  result: Record<string, unknown>
+  displayName?: string
+  note?: string
+}
+
+/** File artifact create — handler maps to save_analysis_file_artifact (create-only: a reused key conflicts). */
+export interface FileArtifactCreatePayload extends ArtifactSavePayloadBase {
+  kind: 'file'
+  mode: 'create'
+  file: File
+  /** Maps to the Python `kind=` argument (defaults to "file" backend-side). */
+  fileKind: string
+  filename?: string
+  displayName?: string
+  note?: string
+  contentType?: string
+  metadata?: Record<string, unknown>
+}
+
+/**
+ * File artifact replacement — handler maps to update_analysis_file_artifact
+ * (transactional CAS replace). `kind` and `filename` are immutable backend-side, so
+ * `fileKind` echoes the artifact's existing kind and no filename is carried. `note`
+ * is three-state: omitted preserves, null clears, a string sets. `metadata` REPLACES
+ * the previous result metadata rather than merging, so it always carries the full
+ * intended map — omitting it clears whatever was there.
+ */
+export interface FileArtifactUpdatePayload extends ArtifactSavePayloadBase {
+  kind: 'file'
+  mode: 'update'
+  file: File
+  fileKind: string
+  note?: string | null
+  contentType?: string
+  metadata?: Record<string, unknown>
+}
+
+/**
+ * File artifact create where the plugin handler produces the bytes itself.
+ * This is intended for server-side serialization of in-memory analysis state;
+ * the browser neither fabricates nor uploads a placeholder File.
+ */
+export interface HandlerFileArtifactCreatePayload extends ArtifactSavePayloadBase {
+  kind: 'file'
+  mode: 'create'
+  source: 'handler'
+  fileKind: string
+  displayName?: string
+  note?: string
+  metadata?: Record<string, unknown>
+}
+
+/** File artifact replacement where the plugin handler produces the bytes itself. */
+export interface HandlerFileArtifactUpdatePayload extends ArtifactSavePayloadBase {
+  kind: 'file'
+  mode: 'update'
+  source: 'handler'
+  fileKind: string
+  note?: string | null
+  metadata?: Record<string, unknown>
+}
+
+export type ArtifactSavePayload =
+  | JsonArtifactSavePayload
+  | FileArtifactCreatePayload
+  | FileArtifactUpdatePayload
+
+/** Payloads accepted when `ArtifactSaveDialog.fileSource` is `handler`. */
+export type HandlerArtifactSavePayload =
+  | JsonArtifactSavePayload
+  | HandlerFileArtifactCreatePayload
+  | HandlerFileArtifactUpdatePayload
+
+/** Every payload variant the dialog can emit across both file sources. */
+export type ArtifactSaveDialogPayload =
+  | ArtifactSavePayload
+  | HandlerFileArtifactCreatePayload
+  | HandlerFileArtifactUpdatePayload
+
+/** Optional handler result; cleanupPending surfaces AnalysisFileArtifactUpdate.cleanup_pending. */
+export interface ArtifactSaveResult {
+  artifact?: AnalysisArtifactSummary
+  cleanupPending?: boolean
+}
+
+/**
+ * Plugin-supplied save handler. The dialog never writes to the platform;
+ * the handler forwards the payload to the plugin backend, which calls
+ * save_analysis_artifact / save_analysis_file_artifact / update_analysis_file_artifact.
+ */
+export type ArtifactSaveHandler = (
+  payload: ArtifactSavePayload,
+) => Promise<ArtifactSaveResult | void>
+
+/** Save handler paired with `ArtifactSaveDialog.fileSource="handler"`. */
+export type HandlerArtifactSaveHandler = (
+  payload: HandlerArtifactSavePayload,
+) => Promise<ArtifactSaveResult | void>
+
+/** Handler accepted by ArtifactSaveDialog; `fileSource` selects the payload family. */
+export type ArtifactSaveDialogHandler = ArtifactSaveHandler | HandlerArtifactSaveHandler

package/src/types/auth.ts

@@ -0,0 +1,59 @@
+import type { RoleInfo } from '../permissions'
+
+// Authentication configuration
+export interface AuthConfig {
+  authRequired: boolean
+  passkeyEnabled: boolean
+  passkeyRegistered: boolean
+  registrationEnabled: boolean
+  databaseMode: string
+  experimentVisibilityMode?: 'open' | 'restricted'
+}
+
+// User information
+export interface UserInfo {
+  id: number
+  username: string
+  shortname: string | null
+  email: string | null
+  role: string
+  roleObj?: RoleInfo | null
+  isActive: boolean
+}
+
+// Login response from API
+export interface LoginResponse {
+  access_token: string
+  token_type: string
+  expires_in: number
+}
+
+// Token verification response
+export interface TokenVerifyResponse {
+  valid: boolean
+  username: string | null
+  expires_at: string | null
+}
+
+// Registration request
+export interface RegisterRequest {
+  username: string
+  password: string
+  email?: string
+  shortname?: string
+}
+
+// Profile update request
+export interface UpdateProfileRequest {
+  email?: string
+  shortname?: string
+  current_password?: string
+  new_password?: string
+}
+
+// Passkey credential info
+export interface CredentialInfo {
+  credential_id: string
+  device_name: string | null
+  created_at: string
+}

package/src/types/auto-group.ts

@@ -0,0 +1,157 @@
+import type { SampleGroup } from './components'
+import type { TreeNode } from './componentLabTypes'
+
+// ---- Legacy (kept for source-compatibility) ----
+export type OutlierAction = 'include' | 'exclude' | 'qc'
+export type InputMode = 'paste' | 'csv' | 'experiment'
+
+export interface OutlierInfo {
+  sample: string
+  index: number
+  fieldCount: number
+  action: OutlierAction
+}
+
+export interface MetadataRow {
+  sampleName: string
+  fields: Record<string, string>
+  group: string
+}
+
+export interface ParsedCsvData {
+  columns: string[]
+  rows: Record<string, string>[]
+  sampleColumn: string
+  delimiter: string
+}
+
+// ---- Class detection ----
+
+export type SampleClassKind =
+  | 'biological'
+  | 'iqc'
+  | 'eqc'
+  | 'standard'
+  | 'spike-in'
+  | 'stock'
+  | 'blank'
+  | 'unknown'
+
+export type ClassDisposition = 'group' | 'overlay' | 'exclude'
+
+export interface SampleClass {
+  kind: SampleClassKind
+  label: string
+  subKind?: string
+  members: number[]
+  classTagPositions: number[]
+  disposition: ClassDisposition
+  /**
+   * Token count shared by every member of this class. Set by `splitByTokenLength`
+   * after type classification so that samples with different field counts never
+   * share a schema — column index N then means the same field for every member.
+   */
+  tokenLength?: number
+}
+
+// ---- Column / role classifier ----
+
+export type ColumnRole =
+  | 'constant'
+  | 'factor'
+  | 'replicate'
+  | 'run-order'
+  | 'numeric'
+  | 'class-tag'
+  | 'ignore'
+
+export interface NumericParse {
+  value: number
+  unit: string
+  raw: string
+}
+
+export interface NumericBinning {
+  mode: 'discrete' | 'binned'
+  edges?: number[]
+  labels?: string[]
+}
+
+export interface ValueOps {
+  alias?: Record<string, string>
+  exclude?: string[]
+}
+
+export interface ColumnInfo {
+  index: number
+  name: string
+  sourceIndices: number[]
+  uniqueValues: string[]
+  cardinality: number
+  /** Legacy field, retained alongside `role` during the shim window. */
+  type?: 'prefix' | 'suffix'
+  role?: ColumnRole
+  numeric?: { byValue: Record<string, NumericParse> }
+  binning?: NumericBinning
+  ops?: ValueOps
+  /** Original CSV column header — used for row lookups when name is renamed */
+  originalName?: string
+  displayName?: string
+}
+
+export interface ClassSchema {
+  classKind: SampleClassKind
+  subKind?: string
+  /** Token count of the class this schema describes. Distinguishes schemas that
+   *  share a (kind, subKind) but were split apart by token-length. */
+  tokenLength?: number
+  columns: ColumnInfo[]
+  groupBy: number[]
+  replicateColumn?: number
+}
+
+export interface MergeSuggestion {
+  classKind: SampleClassKind
+  subKind?: string
+  columnIndices: number[]
+  proposedName: string
+  confidence: number
+}
+
+export interface AutoGroupResult {
+  /** All emitted groups, experimental + overlay concatenated for source compat. */
+  groups: SampleGroup[]
+  /** Class disposition === 'group' only. */
+  experimentalGroups?: SampleGroup[]
+  /** Class disposition === 'overlay' only. */
+  qcGroups?: SampleGroup[]
+  metadata: MetadataRow[]
+  excludedSamples: string[]
+  schemas?: ClassSchema[]
+  fingerprint?: SchemaFingerprint
+  /**
+   * Experimental (disposition === 'group') classes as a nested hierarchy:
+   * one root per class, then one level per enabled groupBy column, then the
+   * sample leaves. Parent nodes carry a sample-count `badge`; leaves carry the
+   * sample name plus the detected injection number (`metadata.injection` and as
+   * the leaf badge). Renders directly in `SampleHierarchyTree`.
+   */
+  groupTree?: TreeNode[]
+}
+
+export interface SchemaFingerprint {
+  version: 1
+  classes: Array<{
+    kind: SampleClassKind
+    subKind?: string
+    tokenLength?: number
+    columns: Array<{
+      name: string
+      role: ColumnRole
+      sourceIndices: number[]
+      binning?: NumericBinning
+      ops?: ValueOps
+    }>
+    groupBy: number[]
+  }>
+}

package/src/types/componentLabTypes.ts

@@ -0,0 +1,235 @@
+// Well Plate types
+export type WellPlateFormat = 6 | 12 | 24 | 48 | 54 | 96 | 384
+export type WellState = 'empty' | 'filled' | 'selected' | 'disabled'
+export type WellPlateSelectionMode = 'none' | 'single' | 'multiple' | 'rectangle' | 'drag'
+export type WellPlateSize = 'sm' | 'md' | 'lg' | 'xl' | 'fill'
+export type WellShape = 'circle' | 'rounded'
+
+export interface Well {
+  id: string
+  row: number
+  col: number
+  state: WellState
+  sampleType?: string
+  value?: number
+  metadata?: Record<string, unknown>
+}
+
+export type HeatmapColorScale = 'viridis' | 'plasma' | 'turbo' | 'custom'
+
+export interface HeatmapConfig {
+  enabled: boolean
+  min?: number
+  max?: number
+  colorScale?: HeatmapColorScale
+  customColors?: string[]
+  showLegend?: boolean
+}
+
+// Slot position for rack color coding
+export type SlotPosition = 'R' | 'G' | 'B' | 'Y'
+
+// Extended well data stored in Well.metadata
+export interface WellExtendedData {
+  label?: string
+  injectionVolume?: number
+  injectionCount?: number
+  customMethod?: string | null
+}
+
+// Data emitted when editing a well
+export interface WellEditData {
+  wellId: string
+  label: string
+  sampleType: string
+  injectionVolume: number
+  injectionCount: number
+  customMethod: string
+}
+
+// Fields shown in the edit popup
+export type WellEditField = 'label' | 'sampleType' | 'injectionVolume' | 'injectionCount' | 'customMethod'
+
+// External sample drop payloads for WellPlate / RackEditor
+export interface WellSampleDropData {
+  id?: string
+  sampleName?: string
+  label?: string
+  sampleType?: string
+  injectionVolume?: number
+  injectionCount?: number
+  customMethod?: string | null
+  metadata?: Record<string, unknown>
+  raw?: unknown
+}
+
+export interface WellSampleDropContext {
+  wellId: string
+  event: DragEvent
+}
+
+export type WellSampleDropParser = (
+  event: DragEvent,
+  context: WellSampleDropContext
+) => WellSampleDropData | null | undefined
+
+// Legend item for sample type display
+export interface WellLegendItem {
+  type: string
+  label: string
+  color: string
+}
+
+// Condition headers for dose-response / drug treatment plates
+export interface PlateCondition {
+  label: string
+  color: string
+  concentrations: number[]
+  unit?: string
+}
+
+export interface ColumnCondition extends PlateCondition {
+  cols: number[]
+}
+
+export interface RowCondition extends PlateCondition {
+  rows: string[]
+}
+
+// Rack for RackEditor
+export interface Rack {
+  id: string
+  name: string
+  format: WellPlateFormat
+  slot: SlotPosition
+  injectionVolume: number
+  wells: Record<string, Partial<Well>>
+}
+
+export interface RackSampleDropContext {
+  rack: Rack
+  rackId: string
+  wellId: string
+  event: DragEvent
+}
+
+export type RackSampleDropMapper = (
+  data: WellSampleDropData,
+  context: RackSampleDropContext
+) => WellEditData | null | undefined
+
+// Sample Legend types
+export interface SampleType {
+  id: string
+  name: string
+  color?: string
+  count?: number
+  description?: string
+}
+
+// Plate Map Editor types
+export interface PlateMap {
+  id: string
+  name: string
+  format: WellPlateFormat
+  wells: Record<string, Well>
+}
+
+export interface PlateMapEditorState {
+  plates: PlateMap[]
+  activePlateId: string
+  samples: SampleType[]
+  selectedWells: string[]
+  activeSampleId?: string
+}
+
+// Experiment Timeline types
+export type ProtocolStepType = 'incubation' | 'wash' | 'addition' | 'measurement' | 'transfer' | 'centrifuge' | 'mix' | 'custom'
+export type ProtocolStepStatus = 'pending' | 'in_progress' | 'completed' | 'failed' | 'skipped'
+
+export interface ProtocolStep {
+  id: string
+  type: ProtocolStepType
+  name: string
+  description?: string
+  duration?: number
+  status: ProtocolStepStatus
+  parameters?: Record<string, unknown>
+  order: number
+}
+
+// Sample Selector types
+export interface SampleGroup {
+  name: string
+  color: string
+  samples: string[]
+}
+
+// Group Assigner types
+export interface GroupItem {
+  name: string
+  color: string
+  count: number
+}
+
+// FileUploader types
+export type FileUploaderMode = 'file' | 'folder'
+
+// MoleculeInput types
+export interface MoleculeData {
+  smiles: string
+  molfile: string
+}
+
+// ReagentList types
+export type StorageCondition = 'RT' | '4C' | '-20C' | '-80C'
+
+export type ReagentColumn =
+  | 'name'
+  | 'catalog'
+  | 'lot'
+  | 'expiry'
+  | 'storage'
+  | 'location'
+  | 'stock'
+  | 'supplier'
+
+export interface Reagent {
+  id: string
+  name: string
+  catalogNumber?: string
+  lotNumber?: string
+  expiryDate?: Date | string
+  storageCondition?: StorageCondition
+  location?: string
+  stockLevel?: number
+  stockUnit?: string
+  supplier?: string
+  url?: string
+}
+
+// SampleHierarchyTree types
+export type TreeNodeType =
+  | 'study'
+  | 'experiment'
+  | 'plate'
+  | 'sample'
+  | 'cell_line'
+  | 'passage'
+  | 'clone'
+  | 'treatment'
+  | 'folder'
+  | 'custom'
+
+export type BadgeVariant = 'default' | 'success' | 'warning' | 'error'
+
+export interface TreeNode {
+  id: string
+  label: string
+  type?: TreeNodeType
+  icon?: string
+  children?: TreeNode[]
+  metadata?: Record<string, unknown>
+  badge?: string | number
+  badgeVariant?: BadgeVariant
+}