@morscherlab/mint-sdk 1.0.63 → 1.1.0-beta.10

package/README.md

@@ -105,16 +105,31 @@ const result = await pluginClient.analyze(
 )
 ```
 
-Generated files also expose typed plugin settings when the backend declares a
-`settings_model`:
+Generated files also expose typed plugin settings when the backend declares
+`@mint_plugin(config=PluginConfig)`:
 
 ```typescript
-import { useGeneratedPluginSettings } from './generated/mint-plugin'
-
-const { settings } = useGeneratedPluginSettings()
-const threshold = settings.value?.threshold
+import {
+  pluginSettingsFormSchema,
+  pluginSettingsValueSchema,
+  useGeneratedPluginSettings,
+} from './generated/mint-plugin'
+
+const pluginSettings = useGeneratedPluginSettings()
+const threshold = pluginSettings.settings.value?.threshold
+const settingsConfig = pluginSettings.settingsConfig
 ```
 
+Pass `settingsConfig` to `PluginWorkspaceView` or `AppTopBar`.
+`pluginSettingsValueSchema` is the Pydantic JSON Schema used for generated
+TypeScript values. `pluginSettingsFormSchema` is the SDK
+`SettingsModalSchema` used to render controls; they are deliberately separate.
+
+When `.env`, process-environment, or startup values override a field, saving
+still updates its backing value. The effective override remains active, while
+the saved value is returned in `stored_settings` and marked `inactive` until
+that higher-priority override is removed.
+
 The generated client is built from backend plugin metadata, FastAPI routes, and Pydantic schemas, and uses the frontend SDK to resolve the API prefix automatically.
 FastAPI request or response content declared as standard
 `application/octet-stream` is generated as a raw binary transport: request
@@ -345,6 +360,104 @@ replacement path.
 
 ## Composables
 
+### `usePluginJobs(options)`
+
+Generated plugin contracts wrap this composable with definition-specific
+input, job, and output types. For a component dedicated to one generated job,
+bind the definition once with `forDefinition()`:
+
+```typescript
+import { usePluginJobs } from './generated/mint-plugin'
+
+const jobs = usePluginJobs()
+await jobs.ready()
+
+const analyzeJobs = jobs.forDefinition('analyze')
+const job = await analyzeJobs.submit({
+  source: new File(['peak\n1'], 'peaks.csv'),
+  threshold: 0.1,
+})
+const result = await analyzeJobs.loadResult(job)
+const canonicalJob = await analyzeJobs.getJob(job.job_id)
+const completedJob = await analyzeJobs.waitForJob(canonicalJob, {
+  signal: abortController.signal,
+  rejectOnFailure: true,
+})
+
+await analyzeJobs.cancelJob(canonicalJob)
+
+// Releases only finished `analyze` jobs and their retained results.
+await analyzeJobs.clearFinishedJobs()
+```
+
+The returned scope exposes a typed `jobs` getter, `isJob()` type guard,
+`submit()`, `getJob()`, `waitForJob()`, `loadResult()`, `cancelJob()`, `deleteJob()`, and
+definition-scoped `clearFinishedJobs()`. It also exposes the generated
+`lifecycle` and `profile` literals for that definition without adding runtime
+requests. Passing a job from another definition
+fails instead of crossing the scope. Capability fields are presentation hints;
+the server remains authoritative when scoped cancel/delete methods are called.
+The root wrapper still supports dynamic definition IDs through `submit()` and
+`jobsFor()`. Its no-argument `clearFinishedJobs()` intentionally clears
+terminal jobs across every definition.
+
+The underlying frontend composable accepts an optional definition ID in
+`clearFinishedJobs(definitionId)`; generated clients expose the scoped method
+so static definition IDs retain their generated input, job, and output types.
+`getJob()` fetches one fresh canonical job without refreshing the list.
+`waitForJob()` settles from the same SSE/poll-backed canonical source and
+cleans up on abort, deletion, or disposal, so callers do not need a second
+event stream or Promise registry. A call made while the runtime is paused
+rejects immediately. Waiting on a known active job tolerates a transient direct
+lookup failure and continues through SSE/poll updates; pausing an existing wait
+suspends those updates until `resume()`.
+`cancelJob()` updates active work, while `deleteJob()` releases one terminal
+job and its retained result. Background work can be `pause()`d and `resume()`d,
+while `dispose()` is idempotent and also runs automatically with the owning Vue
+effect scope.
+
+Both ordinary `uploadPath({ ..., signal })` and a staged scope's
+`uploadPart(job, { ..., signal })` forward the supplied `AbortSignal` to the
+authenticated multipart request. Abort stops the client-side transfer, but the
+caller should refresh job/staging state before retrying because the server may
+already have committed the upload.
+Automatic submission binds ordinary Path uploads to its job definition. When
+uploading manually for an administrator-protected definition, call
+`uploadPath(input, definitionId)` so the server can authorize and bind the
+upload before reading its body.
+
+`cancelJob()` and `deleteJob()` accept either a canonical job object or its ID.
+
+Pass the runtime's canonical source directly to standard job UI. The job center
+derives its groups from the same jobs ref and does not mirror it with a watcher:
+
+```vue
+<script setup lang="ts">
+import { JobsStatusTray } from '@morscherlab/mint-sdk'
+import { usePluginJobs } from './generated/mint-plugin'
+
+const jobs = usePluginJobs()
+</script>
+
+<template>
+  <JobsStatusTray :source="jobs" />
+</template>
+```
+
+The older `jobs` plus `adapter` tray inputs remain available for compatibility.
+New integrations should pass the runtime itself so polling, SSE updates, and
+job actions continue to have exactly one state owner.
+
+When an incremental migration temporarily has more than one owner, use
+`combinePluginJobSources([sdkJobs, legacyJobs])`. It preserves each source's
+live jobs getter, fans out refresh/clear operations, routes per-job actions to
+the owning source, and rejects duplicate IDs instead of guessing.
+
+Job state exposes `definition_id`, `result_status`, and `result_expires_at`.
+Managed file results carry a short-lived, result-scoped `download_url` instead
+of embedded base64 data or the user's bearer token, so regular browser
+downloads work through an integrated plugin proxy.
+
 ### `useApi(options?)`
 Generic API client with auth interceptor.