dataiku-sdk 3.2.0 → 3.3.0

package/dist/src/resources/scenarios.js

@@ -1,9 +1,9 @@
 import { randomUUID, } from "node:crypto";
-import { DataikuError, } from "../errors.js";
+import { ClientValidationError, DataikuError, } from "../errors.js";
 import { ScenarioDetailsSchema, ScenarioStatusSchema, ScenarioSummaryArraySchema, } from "../schemas.js";
 import { deepMerge, } from "../utils/deep-merge.js";
-import { BaseResource, } from "./base.js";
-import { computeNextPollDelayMs, } from "./jobs.js";
+import { computeNextPollDelayMs, isRequestDeadlineError, } from "../utils/polling.js";
+import { BaseResource, requireArrayResponse, requireNonEmpty, } from "./base.js";
 export const SCENARIO_CANONICAL_EDITABLE_FIELDS = [
     "params.steps",
     "params.triggers",
@@ -12,6 +12,8 @@ export const SCENARIO_CANONICAL_EDITABLE_FIELDS = [
     "active",
     "name",
 ];
+/** Default byte cap applied when fetching a scenario run log. */
+export const DEFAULT_SCENARIO_MAX_LOG_BYTES = 1_048_576;
 /**
  * Wraps a primary code-run failure so the original error (and its taxonomy:
  * category, exit-code semantics) stays intact while the concurrent throwaway
@@ -30,6 +32,53 @@ export class ScenarioScriptRunWithCleanupFailureError extends Error {
 const DEFAULT_CODE_RUN_MAX_LOG_BYTES = 1_048_576;
 const CODE_RUN_OUTPUT_START = "<<<DSS_CODE_RUN_OUTPUT_b7e3a1>>>";
 const CODE_RUN_OUTPUT_END = "<<<DSS_CODE_RUN_OUTPUT_END_b7e3a1>>>";
+/** Prefer the current runId field, with the legacy id field as fallback. */
+function triggerRunIdOf(trigger, scenarioId) {
+    const runId = trigger?.runId ?? trigger?.id;
+    if (typeof runId !== "string" || runId.trim().length === 0) {
+        throw new DataikuError(200, "Unexpected Response", `Scenario${scenarioId ? ` "${scenarioId}"` : ""} run response did not contain a usable run identifier.`);
+    }
+    return runId;
+}
+function triggerQueryOf(trigger) {
+    const triggerObj = trigger.trigger;
+    const triggerId = triggerObj?.id ?? "manual";
+    const triggerRunId = triggerRunIdOf(trigger);
+    return `triggerId=${encodeURIComponent(triggerId)}&triggerRunId=${encodeURIComponent(triggerRunId)}`;
+}
+/** A finite number, or undefined for anything else (absent/malformed JSON fields). */
+function optionalNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+/** Map one get-last-runs entry to a ScenarioRunSummary, tolerating missing fields. */
+function scenarioRunSummaryFromRaw(entry) {
+    if (!isRecord(entry))
+        return { runId: "unknown", };
+    const runId = typeof entry.runId === "string" ? entry.runId : "unknown";
+    const optionalRecord = (value) => isRecord(value) ? value : undefined;
+    return {
+        runId,
+        ...(optionalNumber(entry.start) !== undefined ? { start: optionalNumber(entry.start), } : {}),
+        ...(optionalNumber(entry.end) !== undefined ? { end: optionalNumber(entry.end), } : {}),
+        ...(optionalRecord(entry.scenario) !== undefined
+            ? { scenario: optionalRecord(entry.scenario), }
+            : {}),
+        ...(optionalRecord(entry.variables) !== undefined
+            ? { variables: optionalRecord(entry.variables), }
+            : {}),
+        ...(optionalRecord(entry.result) !== undefined
+            ? { result: optionalRecord(entry.result), }
+            : {}),
+    };
+}
+/** Map a light-endpoint response to the documented ScenarioWithStatus shape. */
+function scenarioLightStatusFromRaw(raw) {
+    return {
+        ...(typeof raw.id === "string" ? { id: raw.id, } : {}),
+        ...(typeof raw.running === "boolean" ? { running: raw.running, } : {}),
+        ...(typeof raw.active === "boolean" ? { active: raw.active, } : {}),
+    };
+}
 /**
  * Wrap a user Python script so its stdout/stderr (and any traceback) are captured
  * into a buffer and re-emitted between unique markers, isolated from DSS scenario
@@ -290,11 +339,9 @@ export class ScenariosResource extends BaseResource {
     }
     /** Trigger a scenario run. */
     async run(scenarioId, projectKey) {
-        const scEnc = encodeURIComponent(scenarioId);
+        const scEnc = encodeURIComponent(requireNonEmpty(scenarioId, "scenarioId"));
         const result = await this.client.post(`/public/api/projects/${this.enc(projectKey)}/scenarios/${scEnc}/run/`, {});
-        return {
-            runId: result.id ?? result.runId ?? "unknown",
-        };
+        return { runId: triggerRunIdOf(result, scenarioId), };
     }
     /** Get the light/status view of a scenario. */
     async status(scenarioId, projectKey) {
@@ -344,76 +391,27 @@ export class ScenariosResource extends BaseResource {
         // run id; resolve the real run via get-run-for-trigger so a completed scenario
         // is not misreported as a timeout (the trigger id never matches lastRun).
         const trigger = await this.client.post(`${base}/run/`, {});
-        const triggerObj = trigger.trigger;
-        const triggerId = triggerObj?.id ?? "manual";
-        const triggerRunId = String(trigger.runId ?? trigger.id ?? "");
-        if (!triggerRunId) {
-            throw new DataikuError(500, "Scenario run not started", `Scenario "${scenarioId}" run trigger returned no run id; cannot track the run.`);
-        }
-        const trigQuery = `triggerId=${encodeURIComponent(triggerId)}&triggerRunId=${encodeURIComponent(triggerRunId)}`;
-        let runId = "";
-        let outcome = "UNKNOWN";
-        let pollCount = 0;
-        let timedOut = false;
-        while (true) {
-            if (Date.now() - startedAt >= timeout) {
-                outcome = "TIMEOUT";
-                timedOut = true;
-                break;
-            }
-            pollCount += 1;
-            const run = await this.client.get(`${base}/get-run-for-trigger?${trigQuery}`);
-            const scenarioRun = run.scenarioRun;
-            if (scenarioRun) {
-                runId = scenarioRun.runId ?? runId;
-                const result = scenarioRun.result;
-                const finished = result?.outcome;
-                if (finished) {
-                    outcome = finished;
-                    break;
-                }
-            }
-            const nextDelayMs = computeNextPollDelayMs({
-                pollCount,
-                baseIntervalMs,
-                adaptiveEnabled: adaptivePolling,
-            });
-            const { promise, resolve, } = Promise.withResolvers();
-            setTimeout(resolve, Math.min(nextDelayMs, Math.max(1, timeout - (Date.now() - startedAt))));
-            await promise;
-        }
-        const resolvedRunId = runId || triggerRunId;
-        let steps;
-        if (!timedOut && runId) {
-            try {
-                const details = await this.client.get(`${base}/${encodeURIComponent(runId)}/`);
-                const stepRuns = details.stepRuns ?? [];
-                const mapped = stepRuns.map((entry) => {
-                    const stepDef = entry.step;
-                    const stepResult = entry.result;
-                    return {
-                        name: stepDef?.name,
-                        type: stepDef?.type,
-                        outcome: stepResult?.outcome ?? "UNKNOWN",
-                        ...scenarioStepWarningSummary(stepResult),
-                    };
-                });
-                if (mapped.length > 0)
-                    steps = mapped;
-            }
-            catch {
-                // Best-effort diagnostics: never fail the wait because the run report is unavailable.
-            }
-        }
+        const tracked = await this.trackTriggerRun(scenarioId, base, trigger, {
+            startedAt,
+            baseIntervalMs,
+            adaptivePolling,
+            timeout,
+        });
+        const resolvedRunId = tracked.runId || triggerRunIdOf(trigger);
+        const steps = tracked.timedOut || !tracked.runId
+            ? undefined
+            : await this.runStepSummaries(base, tracked.runId);
         return {
             scenarioId,
             runId: resolvedRunId,
-            outcome,
-            success: outcome === "SUCCESS",
+            outcome: tracked.outcome,
+            success: tracked.outcome === "SUCCESS",
             elapsedMs: Date.now() - startedAt,
-            pollCount,
-            ...(triggerRunId !== resolvedRunId ? { triggerRunId, } : {}),
-            ...(timedOut ? { timedOut: true, } : {}),
+            pollCount: tracked.pollCount,
+            ...(triggerRunIdOf(trigger) !== resolvedRunId
+                ? { triggerRunId: triggerRunIdOf(trigger), }
+                : {}),
+            ...(tracked.timedOut ? { timedOut: true, } : {}),
             ...(steps ? { steps, } : {}),
         };
     }
@@ -453,40 +451,21 @@ export class ScenariosResource extends BaseResource {
             });
             await this.client.putVoid(`${base}/payload`, { script: buildCodeRunScript(script), extension: "py", });
             const trigger = await this.client.post(`${base}/run/`, {});
-            const triggerObj = trigger.trigger;
-            const triggerId = triggerObj?.id ?? "manual";
-            const triggerRunId = String(trigger.runId ?? "");
-            if (!triggerRunId) {
-                throw new DataikuError(500, "Scenario run not started", `Scenario "${scenarioId}" run trigger returned no run id; cannot track the run.`);
-            }
-            const trigQuery = `triggerId=${encodeURIComponent(triggerId)}&triggerRunId=${encodeURIComponent(triggerRunId)}`;
-            while (true) {
-                if (Date.now() - startedAt >= timeout) {
-                    outcome = "TIMEOUT";
-                    timedOut = true;
-                    break;
-                }
-                pollCount += 1;
-                const run = await this.client.get(`${base}/get-run-for-trigger?${trigQuery}`);
-                const scenarioRun = run.scenarioRun;
-                if (scenarioRun) {
-                    runId = scenarioRun.runId ?? runId;
-                    const result = scenarioRun.result;
-                    const finished = result?.outcome;
-                    if (finished) {
-                        outcome = finished;
-                        break;
-                    }
-                }
-                const nextDelayMs = computeNextPollDelayMs({
-                    pollCount,
-                    baseIntervalMs,
-                    adaptiveEnabled: adaptivePolling,
-                });
-                await new Promise((r) => setTimeout(r, Math.min(nextDelayMs, Math.max(1, timeout - (Date.now() - startedAt)))));
-            }
+            const tracked = await this.trackTriggerRun(scenarioId, base, trigger, {
+                startedAt,
+                baseIntervalMs,
+                adaptivePolling,
+                timeout,
+            });
+            outcome = tracked.outcome;
+            runId = tracked.runId;
+            pollCount = tracked.pollCount;
+            timedOut = tracked.timedOut;
             if (runId && outcome !== "TIMEOUT") {
-                const limitedLog = await this.client.getTextLimited(`${base}/${encodeURIComponent(runId)}/log`, maxLogBytes);
+                const limitedLog = await this.getRunLog(scenarioId, runId, {
+                    projectKey: opts?.projectKey,
+                    maxLogBytes,
+                });
                 log = limitedLog.text;
                 logTruncated = limitedLog.truncated;
             }
@@ -521,6 +500,153 @@ export class ScenariosResource extends BaseResource {
             cleanup,
         };
     }
+    /**
+     * Abort a running scenario (POST /scenarios/{id}/abort). The call returns as
+     * soon as DSS accepts the abort request; the scenario may take some time to
+     * actually stop, so this does not wait for termination.
+     */
+    async abort(scenarioId, projectKey) {
+        const scEnc = encodeURIComponent(scenarioId);
+        await this.client.post(`/public/api/projects/${this.enc(projectKey)}/scenarios/${scEnc}/abort`);
+    }
+    /** Get the raw last-runs list (GET /scenarios/{id}/get-last-runs/?limit=N). */
+    async getLastRuns(scenarioId, opts) {
+        if (opts?.limit !== undefined && (!Number.isInteger(opts.limit) || opts.limit < 1)) {
+            throw new ClientValidationError(`limit must be a positive integer, got ${opts.limit}.`);
+        }
+        const scEnc = encodeURIComponent(scenarioId);
+        const query = opts?.limit !== undefined ? `?limit=${opts.limit}` : "";
+        const raw = await this.client.get(`/public/api/projects/${this.enc(opts?.projectKey)}/scenarios/${scEnc}/get-last-runs/${query}`);
+        return requireArrayResponse(raw, "scenarios.getLastRuns").map(scenarioRunSummaryFromRaw);
+    }
+    /** Get the details of a specific run (GET /scenarios/{id}/{runId}). */
+    async getRunDetails(scenarioId, runId, opts) {
+        return this.client.get(`/public/api/projects/${this.enc(opts?.projectKey)}/scenarios/${encodeURIComponent(scenarioId)}/${encodeURIComponent(runId)}/`);
+    }
+    /**
+     * Get the log of a scenario run (GET /scenarios/{id}/{runId}/log), optionally
+     * scoped to a single step via `stepId`. The text is byte-bounded: at most
+     * `maxLogBytes` (default 1 MiB) of the beginning of the log is retained and
+     * `truncated` reports whether the cap cut the body.
+     */
+    async getRunLog(scenarioId, runId, opts) {
+        if (opts?.stepId !== undefined)
+            requireNonEmpty(opts.stepId, "stepId");
+        const maxLogBytes = Math.max(0, Math.floor(opts?.maxLogBytes ?? DEFAULT_SCENARIO_MAX_LOG_BYTES));
+        const scEnc = encodeURIComponent(scenarioId);
+        const query = opts?.stepId !== undefined
+            ? `?stepId=${encodeURIComponent(opts.stepId)}`
+            : "";
+        const { text, truncated, } = await this.client.getTextLimited(`/public/api/projects/${this.enc(opts?.projectKey)}/scenarios/${scEnc}/${encodeURIComponent(runId)}/log${query}`, maxLogBytes);
+        return { text, truncated, maxLogBytes, };
+    }
+    /** Get the payload of a (custom) scenario (GET /scenarios/{id}/payload). */
+    async getPayload(scenarioId, opts) {
+        const scEnc = encodeURIComponent(scenarioId);
+        return this.client.get(`/public/api/projects/${this.enc(opts?.projectKey)}/scenarios/${scEnc}/payload`);
+    }
+    /** Update the payload of a (custom) scenario (PUT /scenarios/{id}/payload). */
+    async setPayload(scenarioId, payload, opts) {
+        const scEnc = encodeURIComponent(scenarioId);
+        await this.client.putVoid(`/public/api/projects/${this.enc(opts?.projectKey)}/scenarios/${scEnc}/payload`, payload);
+    }
+    /**
+     * Toggle the active flag through the light endpoints (GET then PUT
+     * /scenarios/{id}/light) without a full-definition round-trip. Returns the
+     * light status observed after the PUT.
+     */
+    async setActive(scenarioId, active, opts) {
+        const scEnc = encodeURIComponent(scenarioId);
+        const base = `/public/api/projects/${this.enc(opts?.projectKey)}/scenarios/${scEnc}/light`;
+        const beforeRaw = await this.client.get(base);
+        const before = typeof beforeRaw.active === "boolean" ? beforeRaw.active : undefined;
+        // DSS parses the light PUT as a full Scenario object: a minimal {id, active} body 400s with
+        // "Could not parse a Scenario from request body" (missing name). Echo the complete GET body
+        // with active overridden — the same contract as the python client's set_definition(with_status).
+        const nextLight = { ...beforeRaw, active, };
+        await this.client.putVoid(base, nextLight);
+        const after = await this.client.get(base);
+        return {
+            scenarioId,
+            active: typeof after.active === "boolean" ? after.active : active,
+            ...(before !== undefined ? { before, } : {}),
+            status: scenarioLightStatusFromRaw(after),
+        };
+    }
+    /**
+     * Poll get-run-for-trigger until the triggered run reports an outcome or the
+     * deadline elapses. Shared by runAndWait and runScript: POST /run/ returns a
+     * TRIGGER run id, which differs from the actual scenario run id, so the real
+     * run is resolved via get-run-for-trigger (the trigger id never matches
+     * lastRun and would misreport a completed scenario as a timeout).
+     */
+    async trackTriggerRun(scenarioId, base, trigger, timing) {
+        triggerRunIdOf(trigger, scenarioId);
+        const trigQuery = triggerQueryOf(trigger);
+        let runId = "";
+        let pollCount = 0;
+        while (true) {
+            if (Date.now() - timing.startedAt >= timing.timeout) {
+                return { runId, outcome: "TIMEOUT", timedOut: true, pollCount, };
+            }
+            pollCount += 1;
+            // Budget the per-poll GET by the remaining wait so a stalling
+            // trigger-status endpoint cannot defeat the overall run deadline.
+            const remainingMs = Math.max(1, timing.timeout - (Date.now() - timing.startedAt));
+            let run;
+            try {
+                run = await this.client.get(`${base}/get-run-for-trigger?${trigQuery}`, { timeoutMs: remainingMs, });
+            }
+            catch (error) {
+                if (!isRequestDeadlineError(error, timing.startedAt + timing.timeout))
+                    throw error;
+                return { runId, outcome: "TIMEOUT", timedOut: true, pollCount, };
+            }
+            const scenarioRun = run.scenarioRun;
+            if (scenarioRun) {
+                runId = scenarioRun.runId ?? runId;
+                const result = scenarioRun.result;
+                const finished = result?.outcome;
+                if (finished) {
+                    return { runId, outcome: finished, timedOut: false, pollCount, };
+                }
+            }
+            const nextDelayMs = computeNextPollDelayMs({
+                pollCount,
+                baseIntervalMs: timing.baseIntervalMs,
+                adaptiveEnabled: timing.adaptivePolling,
+            });
+            const { promise, resolve, } = Promise.withResolvers();
+            setTimeout(resolve, Math.min(nextDelayMs, Math.max(1, timing.timeout - (Date.now() - timing.startedAt))));
+            await promise;
+        }
+    }
+    /**
+     * Best-effort step outcome summaries from the run report
+     * (GET /scenarios/{id}/{runId}). Never fails the wait: an unavailable
+     * run report returns undefined.
+     */
+    async runStepSummaries(base, runId) {
+        try {
+            const details = await this.client.get(`${base}/${encodeURIComponent(runId)}/`);
+            const stepRuns = details.stepRuns ?? [];
+            const mapped = stepRuns.map((entry) => {
+                const stepDef = entry.step;
+                const stepResult = entry.result;
+                return {
+                    name: stepDef?.name,
+                    type: stepDef?.type,
+                    outcome: stepResult?.outcome ?? "UNKNOWN",
+                    ...scenarioStepWarningSummary(stepResult),
+                };
+            });
+            return mapped.length > 0 ? mapped : undefined;
+        }
+        catch {
+            // Best-effort diagnostics: never fail the wait because the run report is unavailable.
+            return undefined;
+        }
+    }
     /**
      * Delete the throwaway scenario at the end of a code run, or report the
      * explicit keep outcome. Never throws: delete failures are surfaced in the

package/dist/src/resources/sql.js

@@ -101,7 +101,11 @@ function withSqlErrorContext(error) {
             catch {
                 body = `SQL query failed: ${detail}\n${error.body}`;
             }
-            throw new DataikuError(error.status, error.statusText, body, error.retry, error.requestId, { target: error.trustedTarget, elapsedMs: error.trustedElapsedMs, });
+            throw new DataikuError(error.status, error.statusText, body, error.retry, error.requestId, {
+                target: error.trustedTarget,
+                elapsedMs: error.trustedElapsedMs,
+                bodyTruncated: error.bodyTruncated,
+            });
         }
     }
     throw error;

package/dist/src/resources/users.d.ts

@@ -0,0 +1,129 @@
+import type { FutureState } from "../schemas.js";
+import { BaseResource } from "./base.js";
+/**
+ * A DSS user as returned by the admin Security endpoints. The documented
+ * attributes below are stable; DSS may return undocumented extra attributes
+ * (per the API docs they must not be modified on update), so they are preserved
+ * under `Record<string, unknown>` and are never stripped by this SDK.
+ */
+export interface DssUser extends Record<string, unknown> {
+    login?: string;
+    sourceType?: string;
+    displayName?: string;
+    groups?: string[];
+    /** "True if the user is allowed to write native code" (string or boolean per DSS). */
+    codeAllowed?: unknown;
+    email?: string;
+    password?: string;
+    userProfile?: string;
+}
+/**
+ * Last activity timestamps for one user. Epoch-millisecond timestamps are
+ * absent for a user who has never logged in or whose session was never loaded.
+ */
+export interface UserActivity extends Record<string, unknown> {
+    login?: string;
+    lastSuccessfulLogin?: number | null;
+    lastFailedLogin?: number | null;
+    lastLoaded?: number | null;
+}
+/**
+ * One entry of the external-users listing: an externally sourced user together
+ * with its provisioning status against DSS groups/profiles.
+ */
+export interface ExternalUserEntry extends Record<string, unknown> {
+    status?: string;
+    userAttributes?: Record<string, unknown>;
+    profile?: string;
+}
+/**
+ * Body of `POST /admin/users` (create). `login` is required by DSS; everything
+ * else is optional because DSS accepts partial definitions and fills defaults.
+ * Secret attributes (e.g. `password`) are forwarded verbatim over TLS but must
+ * never be logged — see the CLI-layer redaction in commands/user.ts.
+ */
+export interface UserCreateRequest extends Record<string, unknown> {
+    login: string;
+    sourceType?: string;
+    displayName?: string;
+    email?: string;
+    groups?: string[];
+    userProfile?: string;
+    password?: string;
+}
+/**
+ * Body of `POST /admin/users/actions/provision`. Each provisioned user carries
+ * the source (external) group names and the DSS group names to map them to.
+ */
+export interface ProvisionRequest extends Record<string, unknown> {
+    userSourceType: string;
+    users: Array<{
+        login?: string;
+        displayName?: string;
+        email?: string;
+        sourceGroupNames?: string[];
+        dkuGroupNames?: string[];
+    }>;
+}
+export declare class UsersResource extends BaseResource {
+    /**
+     * Retrieves the list of DSS users (Admin required).
+     *
+     * With `connected: true`, DSS additionally reports which users are currently
+     * connected. The connected status is detected over WebSockets per the docs;
+     * disabled WebSockets make some or all connected users report as offline.
+     */
+    list(opts?: {
+        connected?: boolean;
+    }): Promise<DssUser[]>;
+    /** Retrieves a User object describing a DSS user (Admin required). */
+    get(login: string): Promise<DssUser>;
+    /**
+     * Adds a user account on DSS (Admin required). DSS answers 201 with
+     * `{msg: "Created user <login>"}`; the raw server record is returned as-is.
+     */
+    create(body: UserCreateRequest): Promise<Record<string, unknown>>;
+    /**
+     * Updates a user (Admin required). Per the docs the body MUST have been
+     * obtained from a prior GET at the same URL; undocumented attributes should
+     * be passed through unmodified. DSS answers with `{msg: "Edited user ..."}`.
+     */
+    update(login: string, body: DssUser): Promise<Record<string, unknown>>;
+    /** Deletes a DSS user (Admin required). */
+    delete(login: string): Promise<{
+        deleted: string;
+    }>;
+    /**
+     * Resyncs one user (Admin required). Returns a DSS future reference; poll
+     * with `client.futures` when the result is not inline.
+     */
+    resync(login: string): Promise<FutureState>;
+    /**
+     * Resyncs multiple users (Admin required). Body is a plain array of logins
+     * per the docs. Returns a future reference.
+     */
+    resyncMulti(logins: string[]): Promise<FutureState>;
+    /**
+     * Fetches externally sourced users and their provisioning status
+     * (Admin required). Returns a future whose `result` (when present) is an
+     * array of {@link ExternalUserEntry}; poll with `client.futures` when
+     * `hasResult` is false.
+     */
+    externalUsers(): Promise<FutureState>;
+    /**
+     * Fetches externally sourced groups (Admin required). Returns a future whose
+     * `result` (when present) is an array of group-name strings; poll with
+     * `client.futures` when `hasResult` is false.
+     */
+    externalGroups(): Promise<FutureState>;
+    /**
+     * Provisions users from an external source (Admin required). Body is the
+     * documented `{userSourceType, users[]}` request. Returns a future whose
+     * result carries a provisioning summary; poll with `client.futures`.
+     */
+    provision(body: ProvisionRequest): Promise<FutureState>;
+    /** Gets the last activity timestamps for all users (Admin required). */
+    activityAll(): Promise<UserActivity[]>;
+    /** Gets the last activity timestamps for one user (Admin required). */
+    activity(login: string): Promise<UserActivity>;
+}

package/dist/src/resources/users.js

@@ -0,0 +1,128 @@
+import { ClientValidationError, } from "../errors.js";
+import { FutureStateSchema, } from "../schemas.js";
+import { BaseResource, requireArrayResponse, requireNonEmpty, } from "./base.js";
+function validateGroupsBody(body, method) {
+    if (body.groups !== undefined && !Array.isArray(body.groups)) {
+        throw new ClientValidationError(`${method}: groups must be an array of group names.`);
+    }
+}
+export class UsersResource extends BaseResource {
+    /**
+     * Retrieves the list of DSS users (Admin required).
+     *
+     * With `connected: true`, DSS additionally reports which users are currently
+     * connected. The connected status is detected over WebSockets per the docs;
+     * disabled WebSockets make some or all connected users report as offline.
+     */
+    async list(opts) {
+        const params = new URLSearchParams();
+        if (opts?.connected !== undefined)
+            params.set("connected", String(opts.connected));
+        const query = params.toString();
+        const raw = await this.client.get(`/public/api/admin/users/${query ? `?${query}` : ""}`);
+        return requireArrayResponse(raw, "users.list");
+    }
+    /** Retrieves a User object describing a DSS user (Admin required). */
+    async get(login) {
+        const enc = requireNonEmpty(login, "login").trim();
+        return this.client.get(`/public/api/admin/users/${encodeURIComponent(enc)}`);
+    }
+    /**
+     * Adds a user account on DSS (Admin required). DSS answers 201 with
+     * `{msg: "Created user <login>"}`; the raw server record is returned as-is.
+     */
+    async create(body) {
+        if (typeof body?.login !== "string" || body.login.trim().length === 0) {
+            throw new ClientValidationError("users.create: body.login is required.");
+        }
+        validateGroupsBody(body, "users.create");
+        return this.client.post("/public/api/admin/users", body);
+    }
+    /**
+     * Updates a user (Admin required). Per the docs the body MUST have been
+     * obtained from a prior GET at the same URL; undocumented attributes should
+     * be passed through unmodified. DSS answers with `{msg: "Edited user ..."}`.
+     */
+    async update(login, body) {
+        const enc = requireNonEmpty(login, "login").trim();
+        if (body === null || body === undefined || typeof body !== "object" || Array.isArray(body)) {
+            throw new ClientValidationError("users.update: body must be a User object.");
+        }
+        validateGroupsBody(body, "users.update");
+        return this.client.put(`/public/api/admin/users/${encodeURIComponent(enc)}`, body);
+    }
+    /** Deletes a DSS user (Admin required). */
+    async delete(login) {
+        const enc = requireNonEmpty(login, "login").trim();
+        await this.client.del(`/public/api/admin/users/${encodeURIComponent(enc)}`);
+        return { deleted: enc, };
+    }
+    /**
+     * Resyncs one user (Admin required). Returns a DSS future reference; poll
+     * with `client.futures` when the result is not inline.
+     */
+    async resync(login) {
+        const enc = requireNonEmpty(login, "login").trim();
+        const raw = await this.client.post(`/public/api/admin/users/${encodeURIComponent(enc)}/actions/resync`);
+        return this.client.safeParse(FutureStateSchema, raw, "users.resync");
+    }
+    /**
+     * Resyncs multiple users (Admin required). Body is a plain array of logins
+     * per the docs. Returns a future reference.
+     */
+    async resyncMulti(logins) {
+        if (!Array.isArray(logins) || logins.length === 0
+            || logins.some((l) => typeof l !== "string" || l.trim().length === 0)) {
+            throw new ClientValidationError("users.resyncMulti: logins must be a non-empty array of logins.");
+        }
+        const raw = await this.client.post("/public/api/admin/users/actions/resync-multi", logins);
+        return this.client.safeParse(FutureStateSchema, raw, "users.resyncMulti");
+    }
+    /**
+     * Fetches externally sourced users and their provisioning status
+     * (Admin required). Returns a future whose `result` (when present) is an
+     * array of {@link ExternalUserEntry}; poll with `client.futures` when
+     * `hasResult` is false.
+     */
+    async externalUsers() {
+        const raw = await this.client.get("/public/api/admin/users/actions/external-users");
+        return this.client.safeParse(FutureStateSchema, raw, "users.externalUsers");
+    }
+    /**
+     * Fetches externally sourced groups (Admin required). Returns a future whose
+     * `result` (when present) is an array of group-name strings; poll with
+     * `client.futures` when `hasResult` is false.
+     */
+    async externalGroups() {
+        const raw = await this.client.get("/public/api/admin/users/actions/external-groups");
+        return this.client.safeParse(FutureStateSchema, raw, "users.externalGroups");
+    }
+    /**
+     * Provisions users from an external source (Admin required). Body is the
+     * documented `{userSourceType, users[]}` request. Returns a future whose
+     * result carries a provisioning summary; poll with `client.futures`.
+     */
+    async provision(body) {
+        if (body === null || body === undefined || typeof body !== "object" || Array.isArray(body)) {
+            throw new ClientValidationError("users.provision: body must be an object.");
+        }
+        if (typeof body.userSourceType !== "string" || body.userSourceType.trim().length === 0) {
+            throw new ClientValidationError("users.provision: body.userSourceType is required.");
+        }
+        if (!Array.isArray(body.users)) {
+            throw new ClientValidationError("users.provision: body.users must be an array.");
+        }
+        const raw = await this.client.post("/public/api/admin/users/actions/provision", body);
+        return this.client.safeParse(FutureStateSchema, raw, "users.provision");
+    }
+    /** Gets the last activity timestamps for all users (Admin required). */
+    async activityAll() {
+        const raw = await this.client.get("/public/api/admin/users-activity");
+        return requireArrayResponse(raw, "users.activityAll");
+    }
+    /** Gets the last activity timestamps for one user (Admin required). */
+    async activity(login) {
+        const enc = requireNonEmpty(login, "login").trim();
+        return this.client.get(`/public/api/admin/users/${encodeURIComponent(enc)}/activity`);
+    }
+}