@fnndsc/salsa 3.5.1 → 3.6.1

package/dist/plugins/store_import.js.map

@@ -1 +1 @@
-{"version":3,"file":"store_import.js","sourceRoot":"","sources":["../../src/plugins/store_import.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"store_import.js","sourceRoot":"","sources":["../../src/plugins/store_import.ts"],"names":[],"mappings":"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"}

package/dist/retrieve/watch.d.ts

@@ -0,0 +1,114 @@
+import { type Client } from '@fnndsc/cumin';
+/** Lifecycle states of one series retrieve. */
+export type RetrieveStatus = 'pending' | 'pulling' | 'pulled' | 'stalled' | 'timeout' | 'error' | 'unfired';
+/** Progress classification reported to event consumers. */
+export type RetrieveProgressStatus = 'running' | 'done' | 'unconfirmed' | 'error' | 'stalled' | 'timeout';
+/**
+ * Runtime state for a single series being retrieved.
+ *
+ * @property label - Display label for progress and summaries.
+ * @property seriesUID - DICOM SeriesInstanceUID.
+ * @property studyUID - DICOM StudyInstanceUID.
+ * @property pacsName - PACS identifier (`pacs_name` for LONK subscriptions).
+ * @property expectedFiles - File count from the originating query decode.
+ * @property syntheticQueryId - ID of the per-series synthetic PACSQuery.
+ * @property retrieveId - ID of the PACSRetrieve created for it.
+ * @property status - Current lifecycle status.
+ * @property actualFiles - Most recent file count from LONK progress updates.
+ * @property lastProgressFiles - `actualFiles` at the last progress tick (stall detection).
+ * @property lastProgressTime - Timestamp of the last progress tick.
+ * @property startTime - Timestamp when the retrieve was fired.
+ * @property lonkConfirmed - True only after an explicit LONK `done` or a storage confirmation.
+ * @property cubePathDir - CUBE folder the series landed in (resolved post-pull).
+ */
+export interface RetrieveTask {
+    label: string;
+    seriesUID: string;
+    studyUID: string;
+    pacsName: string;
+    expectedFiles: number;
+    syntheticQueryId: number | null;
+    retrieveId: number | null;
+    status: RetrieveStatus;
+    actualFiles: number;
+    lastProgressFiles: number;
+    lastProgressTime: number;
+    startTime: number;
+    lonkConfirmed: boolean;
+    cubePathDir: string | null;
+}
+/**
+ * Consumer callbacks for engine progress.
+ *
+ * @property task - One series changed state or progressed.
+ * @property retryRound - A refire round for unconfirmed series is starting.
+ */
+export interface RetrieveWatchEvents {
+    task?: (task: RetrieveTask, status: RetrieveProgressStatus, phase: 'watching' | 'retrying') => void;
+    retryRound?: (attempt: number, retryMax: number, count: number) => void;
+}
+/**
+ * Builds a fresh retrieve task from series identity facts.
+ *
+ * @param info - Label, UIDs, PACS name, and expected file count.
+ * @returns A pending task ready for {@link retrieve_fireAndWatch}.
+ */
+export declare function retrieveTask_make(info: {
+    label: string;
+    seriesUID: string;
+    studyUID: string;
+    pacsName: string;
+    expectedFiles: number;
+}): RetrieveTask;
+/**
+ * Classifies a task's state for progress reporting.
+ *
+ * @param task - The task to classify.
+ * @returns The progress status consumers render.
+ */
+export declare function retrieveProgress_classify(task: RetrieveTask): RetrieveProgressStatus;
+/**
+ * Marks tasks whose series are already fully registered in CUBE as pulled,
+ * so firing skips them. This is what makes a retrieve idempotent: re-running
+ * the same request after a partial failure fetches only the missing series.
+ *
+ * @param tasks - All tasks; complete ones are mutated to pulled.
+ * @returns How many tasks were marked complete and skipped.
+ */
+export declare function retrieveTasks_skipComplete(tasks: RetrieveTask[]): Promise<number>;
+/**
+ * Fires retrieves for tasks (bounded, retried) without watching: the
+ * fire-and-exit path (`pull --nowait`). Tasks that could not fire are left
+ * in the `unfired` state.
+ *
+ * @param tasks - Tasks to fire.
+ * @param pacsserver - Resolved PACS server identifier.
+ */
+export declare function retrieveTasks_fire(tasks: RetrieveTask[], pacsserver: string): Promise<void>;
+/**
+ * Opens a LONK WebSocket, fires retrieves for the tasks, and blocks until
+ * every task reaches a terminal state. Mutates each task's status,
+ * actualFiles, and lonkConfirmed; reports progress through the events.
+ *
+ * @param tasks - Tasks to subscribe, fire, and watch.
+ * @param pacsserver - Resolved PACS server identifier.
+ * @param client - Authenticated ChRIS API client (for the LONK token).
+ * @param events - Progress callbacks.
+ * @param phase - Phase tag passed through to task events.
+ * @returns Number of tasks whose retrieve could not be fired.
+ */
+export declare function retrieve_fireAndWatch(tasks: RetrieveTask[], pacsserver: string, client: Client, events?: RetrieveWatchEvents, phase?: 'watching' | 'retrying'): Promise<number>;
+/**
+ * Confirms unconfirmed series against CUBE storage and refires the rest, up
+ * to `retryMax` rounds; series still unconfirmed afterwards are marked
+ * errored. This closes the gap between a lost LONK confirmation (cosmetic)
+ * and a retrieve that genuinely never delivered (real loss).
+ *
+ * @param allTasks - All tasks from the initial watch.
+ * @param retryMax - Maximum refire rounds.
+ * @param pacsserver - The PACS server identifier.
+ * @param client - The connected ChRIS client.
+ * @param events - Progress callbacks.
+ * @returns The number of additional firing errors incurred.
+ */
+export declare function retrieve_confirmLoop(allTasks: RetrieveTask[], retryMax: number, pacsserver: string, client: Client, events?: RetrieveWatchEvents): Promise<number>;

package/dist/retrieve/watch.js

@@ -0,0 +1,358 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.retrieveTask_make = retrieveTask_make;
+exports.retrieveProgress_classify = retrieveProgress_classify;
+exports.retrieveTasks_skipComplete = retrieveTasks_skipComplete;
+exports.retrieveTasks_fire = retrieveTasks_fire;
+exports.retrieve_fireAndWatch = retrieve_fireAndWatch;
+exports.retrieve_confirmLoop = retrieve_confirmLoop;
+/**
+ * @file PACS retrieve engine: fire, watch, confirm.
+ *
+ * The single implementation of "make DICOM series land in CUBE and know when
+ * they have": synthetic query+retrieve firing with bounded concurrency and
+ * per-step retry, a LONK WebSocket watch with stall/timeout/no-activity
+ * detection, storage-side confirmation across registration lag, and an
+ * optional refire loop for unconfirmed series. Both consumers (the `pull`
+ * builtin in brasa and the PACS VFS provider's `cp`) previously solved this
+ * independently — LONK push versus 5-second polling — with different
+ * semantics; this module is the convergence (docs/code-audit-2026-08.adoc,
+ * decisions section).
+ *
+ * The engine is presentation-free: progress is reported through the
+ * {@link RetrieveWatchEvents} callbacks and consumers render it however their
+ * surface renders (structured sink progress, plain console lines).
+ *
+ * @module
+ */
+const ws_1 = __importDefault(require("ws"));
+const cumin_1 = require("@fnndsc/cumin");
+/** Concurrent retrieve creations; more overloads CUBE and loses retrieves. */
+const FIRE_CONCURRENCY = 4;
+/** Retry attempts for one retrieve creation, with backoff between them. */
+const FIRE_ATTEMPTS = 3;
+const FIRE_BACKOFF_MS = [250, 500];
+const STALL_TIMEOUT_MS = 30_000;
+const NO_ACTIVITY_TIMEOUT_MS = 15_000;
+const SERIES_TIMEOUT_MS = 5 * 60 * 1_000;
+const CHECKER_INTERVAL_MS = 2_000;
+/**
+ * Builds a fresh retrieve task from series identity facts.
+ *
+ * @param info - Label, UIDs, PACS name, and expected file count.
+ * @returns A pending task ready for {@link retrieve_fireAndWatch}.
+ */
+function retrieveTask_make(info) {
+    return {
+        ...info,
+        syntheticQueryId: null,
+        retrieveId: null,
+        status: 'pending',
+        actualFiles: 0,
+        lastProgressFiles: 0,
+        lastProgressTime: Date.now(),
+        startTime: 0,
+        lonkConfirmed: false,
+        cubePathDir: null,
+    };
+}
+/**
+ * Classifies a task's state for progress reporting.
+ *
+ * @param task - The task to classify.
+ * @returns The progress status consumers render.
+ */
+function retrieveProgress_classify(task) {
+    if (task.status === 'pulled')
+        return task.lonkConfirmed ? 'done' : 'unconfirmed';
+    if (task.status === 'pending' || task.status === 'pulling')
+        return 'running';
+    if (task.status === 'unfired')
+        return 'error';
+    return task.status;
+}
+/**
+ * Marks tasks whose series are already fully registered in CUBE as pulled,
+ * so firing skips them. This is what makes a retrieve idempotent: re-running
+ * the same request after a partial failure fetches only the missing series.
+ *
+ * @param tasks - All tasks; complete ones are mutated to pulled.
+ * @returns How many tasks were marked complete and skipped.
+ */
+async function retrieveTasks_skipComplete(tasks) {
+    let skipped = 0;
+    await Promise.all(tasks.map(async (task) => {
+        const stateResult = await (0, cumin_1.seriesStorage_resolve)(task.seriesUID);
+        if (!stateResult.ok)
+            return;
+        const state = stateResult.value;
+        if (task.expectedFiles > 0 && state.fileCount >= task.expectedFiles && state.folderPath !== null) {
+            task.status = 'pulled';
+            task.lonkConfirmed = true;
+            task.actualFiles = state.fileCount;
+            task.cubePathDir = state.folderPath;
+            skipped++;
+        }
+    }));
+    return skipped;
+}
+/**
+ * Creates a synthetic PACSQuery + PACSRetrieve for a single series, with
+ * bounded retry: creation failures during a server brown-out are permanent
+ * data loss for the run (nothing ever retrieves), so each series gets a few
+ * attempts before it is declared unfired.
+ *
+ * @param task - The task to fire (mutated: syntheticQueryId, retrieveId, startTime, status).
+ * @param pacsserver - Resolved PACS server ID string.
+ */
+async function task_fire(task, pacsserver) {
+    const fired = await (0, cumin_1.retry_untilValue)(FIRE_ATTEMPTS, FIRE_BACKOFF_MS, async () => {
+        const queryData = {
+            // CUBE rejects duplicate query titles per user; a timestamp keeps
+            // re-pull titles unique.
+            title: `pull_${task.seriesUID}_${Date.now().toString(36)}`,
+            query: JSON.stringify({
+                SeriesInstanceUID: task.seriesUID,
+                StudyInstanceUID: task.studyUID,
+            }),
+            execute: false,
+        };
+        const queryResult = await (0, cumin_1.pacsQueries_create)(pacsserver, queryData);
+        if (!queryResult.ok)
+            return null;
+        const retrieveResult = await (0, cumin_1.pacsRetrieve_create)(queryResult.value.id);
+        if (!retrieveResult.ok)
+            return null;
+        return { queryId: queryResult.value.id, retrieveId: retrieveResult.value.id };
+    });
+    if (fired === null) {
+        task.status = 'unfired';
+        return;
+    }
+    task.syntheticQueryId = fired.queryId;
+    task.retrieveId = fired.retrieveId;
+    task.startTime = Date.now();
+}
+/**
+ * Fires retrieves with bounded concurrency, so a large study does not
+ * stampede CUBE with parallel creations (the overload that loses retrieves
+ * in the first place).
+ *
+ * @param tasks - Tasks to fire.
+ * @param pacsserver - Resolved PACS server identifier.
+ */
+async function tasks_fireBounded(tasks, pacsserver) {
+    let next = 0;
+    const worker = async () => {
+        while (next < tasks.length) {
+            const task = tasks[next++];
+            await task_fire(task, pacsserver);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(FIRE_CONCURRENCY, tasks.length) }, () => worker()));
+}
+/**
+ * Fires retrieves for tasks (bounded, retried) without watching: the
+ * fire-and-exit path (`pull --nowait`). Tasks that could not fire are left
+ * in the `unfired` state.
+ *
+ * @param tasks - Tasks to fire.
+ * @param pacsserver - Resolved PACS server identifier.
+ */
+async function retrieveTasks_fire(tasks, pacsserver) {
+    await tasks_fireBounded(tasks, pacsserver);
+}
+/**
+ * Constructs a LONK WebSocket URL from a download token response.
+ *
+ * @param tokenUrl - The download token resource URL.
+ * @param token - The actual download token string.
+ * @returns WebSocket URL for the LONK endpoint.
+ */
+function lonkWsUrl_build(tokenUrl, token) {
+    return tokenUrl
+        .replace(/^http(s?):\/\//, (_m, s) => `ws${s}://`)
+        .replace(/v1\/downloadtokens\/\d+\//, `v1/pacs/ws/?token=${token}`);
+}
+/**
+ * Opens a LONK WebSocket, fires retrieves for the tasks, and blocks until
+ * every task reaches a terminal state. Mutates each task's status,
+ * actualFiles, and lonkConfirmed; reports progress through the events.
+ *
+ * @param tasks - Tasks to subscribe, fire, and watch.
+ * @param pacsserver - Resolved PACS server identifier.
+ * @param client - Authenticated ChRIS API client (for the LONK token).
+ * @param events - Progress callbacks.
+ * @param phase - Phase tag passed through to task events.
+ * @returns Number of tasks whose retrieve could not be fired.
+ */
+async function retrieve_fireAndWatch(tasks, pacsserver, client, events = {}, phase = 'watching') {
+    const emit = (task, status) => {
+        events.task?.(task, status ?? retrieveProgress_classify(task), phase);
+    };
+    const downloadToken = await (0, cumin_1.downloadToken_create)(client);
+    const ws = new ws_1.default(lonkWsUrl_build(downloadToken.url, downloadToken.token));
+    await new Promise((openResolve, openReject) => {
+        ws.once('open', openResolve);
+        ws.once('error', (err) => openReject(err));
+    });
+    for (const t of tasks) {
+        ws.send(JSON.stringify({ SeriesInstanceUID: t.seriesUID, pacs_name: t.pacsName, action: 'subscribe' }));
+    }
+    await tasks_fireBounded(tasks, pacsserver);
+    const fired = tasks.filter((t) => t.status !== 'unfired');
+    const firingErrors = tasks.length - fired.length;
+    if (fired.length === 0) {
+        for (const t of tasks) {
+            if (t.status === 'unfired')
+                emit(t, 'error');
+        }
+        ws.close();
+        return firingErrors;
+    }
+    for (const t of tasks) {
+        emit(t, t.status === 'unfired' ? 'error' : 'running');
+    }
+    const taskByUID = new Map(tasks.map((t) => [t.seriesUID, t]));
+    await new Promise((resolve) => {
+        let resolved = false;
+        const done = () => {
+            if (resolved)
+                return;
+            resolved = true;
+            clearInterval(checker);
+            try {
+                ws.close();
+            }
+            catch { /* best-effort socket cleanup */ }
+            resolve();
+        };
+        const checker = setInterval(() => {
+            const now = Date.now();
+            let allTerminal = true;
+            for (const t of fired) {
+                if (t.status === 'pulled' || t.status === 'error' || t.status === 'unfired' || t.status === 'stalled' || t.status === 'timeout') {
+                    continue;
+                }
+                allTerminal = false;
+                if (t.startTime > 0 && now - t.startTime > SERIES_TIMEOUT_MS) {
+                    t.status = 'timeout';
+                    emit(t, 'timeout');
+                    continue;
+                }
+                if (t.actualFiles > 0 && now - t.lastProgressTime > STALL_TIMEOUT_MS) {
+                    t.status = 'stalled';
+                    emit(t, 'stalled');
+                    continue;
+                }
+                if (t.startTime > 0 && t.actualFiles === 0 && now - t.startTime > NO_ACTIVITY_TIMEOUT_MS) {
+                    t.status = 'pulled';
+                    t.lonkConfirmed = false;
+                    emit(t, 'unconfirmed');
+                    continue;
+                }
+            }
+            if (allTerminal)
+                done();
+        }, CHECKER_INTERVAL_MS);
+        ws.on('message', (data) => {
+            try {
+                const outer = JSON.parse(data.toString());
+                const seriesUID = outer.SeriesInstanceUID;
+                const message = outer.message;
+                if (!seriesUID || !message)
+                    return;
+                const t = taskByUID.get(seriesUID);
+                if (!t)
+                    return;
+                if ('ndicom' in message && typeof message.ndicom === 'number') {
+                    const n = message.ndicom;
+                    t.actualFiles = n;
+                    t.lastProgressFiles = n;
+                    t.lastProgressTime = Date.now();
+                    if (t.status === 'pending')
+                        t.status = 'pulling';
+                    emit(t, 'running');
+                }
+                else if ('done' in message && message.done === true) {
+                    t.status = 'pulled';
+                    t.lonkConfirmed = true;
+                    if (t.actualFiles < t.expectedFiles)
+                        t.actualFiles = t.expectedFiles;
+                    emit(t, 'done');
+                }
+                else if ('error' in message && typeof message.error === 'string') {
+                    t.status = 'error';
+                    emit(t, 'error');
+                }
+            }
+            catch {
+                // Deliberate absorption: a malformed LONK frame carries no correlation
+                // to fail; the checker's stall/timeout guards still bound the watch.
+            }
+        });
+        ws.on('error', () => {
+            for (const t of fired) {
+                if (t.status === 'pending' || t.status === 'pulling') {
+                    t.status = 'error';
+                    emit(t, 'error');
+                }
+            }
+            done();
+        });
+        ws.on('close', () => { done(); });
+    });
+    return firingErrors;
+}
+/**
+ * Confirms unconfirmed series against CUBE storage and refires the rest, up
+ * to `retryMax` rounds; series still unconfirmed afterwards are marked
+ * errored. This closes the gap between a lost LONK confirmation (cosmetic)
+ * and a retrieve that genuinely never delivered (real loss).
+ *
+ * @param allTasks - All tasks from the initial watch.
+ * @param retryMax - Maximum refire rounds.
+ * @param pacsserver - The PACS server identifier.
+ * @param client - The connected ChRIS client.
+ * @param events - Progress callbacks.
+ * @returns The number of additional firing errors incurred.
+ */
+async function retrieve_confirmLoop(allTasks, retryMax, pacsserver, client, events = {}) {
+    let extraFiringErrors = 0;
+    let retryCandidates = allTasks.filter((t) => t.status === 'pulled' && !t.lonkConfirmed);
+    for (let attempt = 1; attempt <= retryMax && retryCandidates.length > 0; attempt++) {
+        await Promise.all(retryCandidates.map(async (t) => {
+            const stateResult = await (0, cumin_1.seriesStorage_resolve)(t.seriesUID);
+            if (stateResult.ok && stateResult.value.folderPath !== null) {
+                t.lonkConfirmed = true;
+                t.cubePathDir = stateResult.value.folderPath;
+            }
+        }));
+        retryCandidates = retryCandidates.filter((t) => !t.lonkConfirmed);
+        if (retryCandidates.length === 0)
+            break;
+        events.retryRound?.(attempt, retryMax, retryCandidates.length);
+        for (const t of retryCandidates) {
+            t.status = 'pending';
+            t.actualFiles = 0;
+            t.lastProgressFiles = 0;
+            t.lastProgressTime = Date.now();
+            t.startTime = 0;
+            t.lonkConfirmed = false;
+            t.syntheticQueryId = null;
+            t.retrieveId = null;
+            events.task?.(t, 'running', 'retrying');
+        }
+        extraFiringErrors += await retrieve_fireAndWatch(retryCandidates, pacsserver, client, events, 'retrying');
+        retryCandidates = retryCandidates.filter((t) => t.status === 'pulled' && !t.lonkConfirmed);
+    }
+    for (const t of retryCandidates) {
+        t.status = 'error';
+        events.task?.(t, 'error', 'retrying');
+    }
+    return extraFiringErrors;
+}
+//# sourceMappingURL=watch.js.map

package/dist/retrieve/watch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch.js","sourceRoot":"","sources":["../../src/retrieve/watch.ts"],"names":[],"mappings":"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"}

package/dist/store/index.d.ts

@@ -1,15 +1,28 @@
+/**
+ * @file Store operations.
+ *
+ * Logic for interacting with the peer ChRIS store (listing, searching).
+ * Failures propagate as Err rather than an empty array, so a store outage is
+ * distinguishable from a store with no plugins; the underlying fetch has
+ * already pushed its reason onto the error stack.
+ *
+ * @module
+ */
+import { Result } from '@fnndsc/cumin';
 /**
  * Lists plugins from the peer store.
  *
  * @param storeUrl - Optional URL of the peer store.
- * @returns Promise resolving to array of raw plugin objects.
+ * @returns Ok with raw plugin objects (possibly empty), or Err when the store
+ *   fetch failed (reason already on the error stack).
  */
-export declare function store_list(storeUrl?: string): Promise<Record<string, unknown>[]>;
+export declare function store_list(storeUrl?: string): Promise<Result<Record<string, unknown>[]>>;
 /**
  * Searches plugins in the peer store.
  *
  * @param query - Search query (e.g. plugin name substring).
  * @param storeUrl - Optional URL of the peer store.
- * @returns Promise resolving to array of raw plugin objects.
+ * @returns Ok with matching raw plugin objects (possibly empty), or Err when
+ *   the store fetch failed (reason already on the error stack).
  */
-export declare function store_search(query: string, storeUrl?: string): Promise<Record<string, unknown>[]>;
+export declare function store_search(query: string, storeUrl?: string): Promise<Result<Record<string, unknown>[]>>;

package/dist/store/index.js

@@ -6,6 +6,9 @@ exports.store_search = store_search;
  * @file Store operations.
  *
  * Logic for interacting with the peer ChRIS store (listing, searching).
+ * Failures propagate as Err rather than an empty array, so a store outage is
+ * distinguishable from a store with no plugins; the underlying fetch has
+ * already pushed its reason onto the error stack.
  *
  * @module
  */
@@ -14,24 +17,26 @@ const cumin_1 = require("@fnndsc/cumin");
  * Lists plugins from the peer store.
  *
  * @param storeUrl - Optional URL of the peer store.
- * @returns Promise resolving to array of raw plugin objects.
+ * @returns Ok with raw plugin objects (possibly empty), or Err when the store
+ *   fetch failed (reason already on the error stack).
  */
 async function store_list(storeUrl) {
     const chrisPlugin = new cumin_1.ChRISPlugin();
     const plugins = await chrisPlugin.plugin_listPeerStore(storeUrl);
-    return plugins || [];
+    return plugins === null ? (0, cumin_1.Err)() : (0, cumin_1.Ok)(plugins);
 }
 /**
  * Searches plugins in the peer store.
  *
  * @param query - Search query (e.g. plugin name substring).
  * @param storeUrl - Optional URL of the peer store.
- * @returns Promise resolving to array of raw plugin objects.
+ * @returns Ok with matching raw plugin objects (possibly empty), or Err when
+ *   the store fetch failed (reason already on the error stack).
  */
 async function store_search(query, storeUrl) {
     const chrisPlugin = new cumin_1.ChRISPlugin();
     // Search by name
     const plugins = await chrisPlugin.plugin_listPeerStore(storeUrl, { name: query });
-    return plugins || [];
+    return plugins === null ? (0, cumin_1.Err)() : (0, cumin_1.Ok)(plugins);
 }
 //# sourceMappingURL=index.js.map

package/dist/store/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/store/index.ts"],"names":[],"mappings":";;AAeA,gCAIC;AASD,oCAKC;AAjCD;;;;;;GAMG;AACH,yCAA4C;AAE5C;;;;;GAKG;AACI,KAAK,UAAU,UAAU,CAAC,QAAiB;IAChD,MAAM,WAAW,GAAgB,IAAI,mBAAW,EAAE,CAAC;IACnD,MAAM,OAAO,GAAqC,MAAM,WAAW,CAAC,oBAAoB,CAAC,QAAQ,CAAC,CAAC;IACnG,OAAO,OAAO,IAAI,EAAE,CAAC;AACvB,CAAC;AAED;;;;;;GAMG;AACI,KAAK,UAAU,YAAY,CAAC,KAAa,EAAE,QAAiB;IACjE,MAAM,WAAW,GAAgB,IAAI,mBAAW,EAAE,CAAC;IACnD,iBAAiB;IACjB,MAAM,OAAO,GAAqC,MAAM,WAAW,CAAC,oBAAoB,CAAC,QAAQ,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IACpH,OAAO,OAAO,IAAI,EAAE,CAAC;AACvB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/store/index.ts"],"names":[],"mappings":";;AAmBA,gCAIC;AAUD,oCAKC;AAtCD;;;;;;;;;GASG;AACH,yCAA6D;AAE7D;;;;;;GAMG;AACI,KAAK,UAAU,UAAU,CAAC,QAAiB;IAChD,MAAM,WAAW,GAAgB,IAAI,mBAAW,EAAE,CAAC;IACnD,MAAM,OAAO,GAAqC,MAAM,WAAW,CAAC,oBAAoB,CAAC,QAAQ,CAAC,CAAC;IACnG,OAAO,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,IAAA,WAAG,GAAE,CAAC,CAAC,CAAC,IAAA,UAAE,EAAC,OAAO,CAAC,CAAC;AAChD,CAAC;AAED;;;;;;;GAOG;AACI,KAAK,UAAU,YAAY,CAAC,KAAa,EAAE,QAAiB;IACjE,MAAM,WAAW,GAAgB,IAAI,mBAAW,EAAE,CAAC;IACnD,iBAAiB;IACjB,MAAM,OAAO,GAAqC,MAAM,WAAW,CAAC,oBAAoB,CAAC,QAAQ,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IACpH,OAAO,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,IAAA,WAAG,GAAE,CAAC,CAAC,CAAC,IAAA,UAAE,EAAC,OAAO,CAAC,CAAC;AAChD,CAAC"}

package/dist/users/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @file CUBE-local account operation facade.
+ * @module
+ */
+import { type LocalAccount, type LocalAccountAction, type Result } from '@fnndsc/cumin';
+export type { LocalAccount, LocalAccountAction, Result };
+/**
+ * Verifies that the current identity may use local-account administration.
+ *
+ * @returns Success when the active CUBE identity has account-admin access.
+ */
+export declare function localAccount_adminAccessEnsure(): Promise<Result<void>>;
+/**
+ * Creates one CUBE-local account.
+ *
+ * @param username - New local username.
+ * @param email - Account email address.
+ * @param password - Initial local-login password.
+ * @returns The created account or an operation error.
+ */
+export declare function localAccount_create(username: string, email: string, password: string): Promise<Result<LocalAccount>>;
+/**
+ * Finds one CUBE-local account by exact username.
+ *
+ * @param username - Exact local username.
+ * @returns The matching account or an operation error.
+ */
+export declare function localAccount_find(username: string): Promise<Result<LocalAccount>>;
+/**
+ * Changes the lifecycle state of one CUBE-local account.
+ *
+ * @param accountID - Stable local-account record identifier.
+ * @param action - Lifecycle transition to apply.
+ * @returns The updated account or an operation error.
+ */
+export declare function localAccount_action(accountID: number, action: LocalAccountAction): Promise<Result<LocalAccount>>;