@datalayer/core 1.1.66 → 1.2.12

package/lib/api/orchestration/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The canonical orchestration model: what one agent says to another about
+ * work it is delegating, supervising, steering, recovering or stopping.
+ *
+ * Every type here is generated from the pydantic models in
+ * `datalayer_core/orchestration`, which are the source of truth
+ * (PLAN_ORCHESTRATOR.md, 19.8), and from the control plane's OpenAPI
+ * document for the answers it wraps them in and the operations it serves.
+ * Regenerate with `npm run generate:orchestration`;
+ * `npm run check:orchestration-generated` is the gate that fails when the
+ * checked-in file is not what the models and the document say. Do not edit
+ * `generated.ts` by hand.
+ *
+ * The wire is camel case, so nothing here converts anything: unlike the MCP
+ * and Contents clients, which speak a snake case wire and camel case in the
+ * browser, an orchestration document is the same in both places.
+ *
+ * `client` is the control plane's twelve commands and two reads, every path
+ * taken from the generated operations; `events` is the subscription that
+ * resumes after a dropped connection, and the user channel's tree
+ * announcement; `measures` is how delegated work is doing, read from the
+ * OTEL service's orchestration dashboard.
+ *
+ * @module api/orchestration
+ */
+export * from './generated';
+export * from './lifecycle';
+export * from './client';
+export * from './events';
+export * from './measures';

package/lib/api/orchestration/index.js

@@ -0,0 +1,34 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * The canonical orchestration model: what one agent says to another about
+ * work it is delegating, supervising, steering, recovering or stopping.
+ *
+ * Every type here is generated from the pydantic models in
+ * `datalayer_core/orchestration`, which are the source of truth
+ * (PLAN_ORCHESTRATOR.md, 19.8), and from the control plane's OpenAPI
+ * document for the answers it wraps them in and the operations it serves.
+ * Regenerate with `npm run generate:orchestration`;
+ * `npm run check:orchestration-generated` is the gate that fails when the
+ * checked-in file is not what the models and the document say. Do not edit
+ * `generated.ts` by hand.
+ *
+ * The wire is camel case, so nothing here converts anything: unlike the MCP
+ * and Contents clients, which speak a snake case wire and camel case in the
+ * browser, an orchestration document is the same in both places.
+ *
+ * `client` is the control plane's twelve commands and two reads, every path
+ * taken from the generated operations; `events` is the subscription that
+ * resumes after a dropped connection, and the user channel's tree
+ * announcement; `measures` is how delegated work is doing, read from the
+ * OTEL service's orchestration dashboard.
+ *
+ * @module api/orchestration
+ */
+export * from './generated.js';
+export * from './lifecycle.js';
+export * from './client.js';
+export * from './events.js';
+export * from './measures.js';

package/lib/api/orchestration/lifecycle.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The canonical execution lifecycle (PLAN_ORCHESTRATOR.md, section 6.1, O0-02).
+ *
+ * The states and the moves between them are not written here: they are
+ * generated from `datalayer_core/orchestration/lifecycle.py`, which is the
+ * source of truth, and this module is the function that reads them. A
+ * mirror that restated the table would be a second place for it to be
+ * wrong, and the whole point of one state machine is that there is one.
+ *
+ * A browser observes; it does not decide. This is here so that a view can
+ * tell whether a control it is about to enable would be refused — a cancel
+ * button on a completed execution — without asking the control plane and
+ * without inventing an answer.
+ *
+ * @module api/orchestration/lifecycle
+ */
+import { type ExecutionState, type LifecycleEvent, type LifecycleMoves } from './generated';
+/** A move the lifecycle does not allow, refused rather than performed. */
+export declare class InvalidTransitionError extends Error {
+    readonly current: ExecutionState;
+    readonly event: LifecycleEvent;
+    constructor(current: ExecutionState, event: LifecycleEvent);
+}
+/** The state of an execution that has been created and nothing more. */
+export declare const INITIAL_STATE: ExecutionState;
+/** The states from which nothing more happens. */
+export declare const TERMINAL_STATES: ReadonlySet<ExecutionState>;
+/** Whether nothing more happens from this state. */
+export declare const isTerminal: (state: ExecutionState) => boolean;
+/** Every event this state accepts, and where each one leads. */
+export declare const movesFrom: (state: ExecutionState) => LifecycleMoves;
+/** Whether the event applies to the state, without moving anything. */
+export declare const canTransition: (current: ExecutionState, event: LifecycleEvent) => boolean;
+/**
+ * The state this event leads to, or a refusal.
+ *
+ * @throws InvalidTransitionError - When the lifecycle does not allow the move.
+ */
+export declare const transition: (current: ExecutionState, event: LifecycleEvent) => ExecutionState;

package/lib/api/orchestration/lifecycle.js

@@ -0,0 +1,57 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * The canonical execution lifecycle (PLAN_ORCHESTRATOR.md, section 6.1, O0-02).
+ *
+ * The states and the moves between them are not written here: they are
+ * generated from `datalayer_core/orchestration/lifecycle.py`, which is the
+ * source of truth, and this module is the function that reads them. A
+ * mirror that restated the table would be a second place for it to be
+ * wrong, and the whole point of one state machine is that there is one.
+ *
+ * A browser observes; it does not decide. This is here so that a view can
+ * tell whether a control it is about to enable would be refused — a cancel
+ * button on a completed execution — without asking the control plane and
+ * without inventing an answer.
+ *
+ * @module api/orchestration/lifecycle
+ */
+import { ORCHESTRATION_LIFECYCLE, } from './generated.js';
+/** A move the lifecycle does not allow, refused rather than performed. */
+export class InvalidTransitionError extends Error {
+    current;
+    event;
+    constructor(current, event) {
+        const reason = isTerminal(current)
+            ? 'it is terminal'
+            : 'that event does not apply there';
+        super(`An execution in '${current}' cannot take '${event}': ${reason}.`);
+        this.name = 'InvalidTransitionError';
+        this.current = current;
+        this.event = event;
+    }
+}
+/** The state of an execution that has been created and nothing more. */
+export const INITIAL_STATE = ORCHESTRATION_LIFECYCLE.initial;
+/** The states from which nothing more happens. */
+export const TERMINAL_STATES = new Set(ORCHESTRATION_LIFECYCLE.terminal);
+/** Whether nothing more happens from this state. */
+export const isTerminal = (state) => TERMINAL_STATES.has(state);
+/** Every event this state accepts, and where each one leads. */
+export const movesFrom = (state) => ORCHESTRATION_LIFECYCLE.transitions[state];
+/** Whether the event applies to the state, without moving anything. */
+export const canTransition = (current, event) => movesFrom(current)[event] !== undefined;
+/**
+ * The state this event leads to, or a refusal.
+ *
+ * @throws InvalidTransitionError - When the lifecycle does not allow the move.
+ */
+export const transition = (current, event) => {
+    const next = movesFrom(current)[event];
+    if (next === undefined) {
+        throw new InvalidTransitionError(current, event);
+    }
+    return next;
+};

package/lib/api/orchestration/measures.d.ts

@@ -0,0 +1,55 @@
+import { type DashboardData, type DashboardDataOptions } from '../otel/dashboards';
+/** The built-in dashboard the measures are read from. */
+export declare const ORCHESTRATION_DASHBOARD = "orchestration";
+/** The panels each measure is read from, by the dashboard's ids. */
+export declare const ORCHESTRATION_PANELS: {
+    readonly afterDisconnect: "orchestration-executions-settled-by-state-where-recovery-disconnected";
+    readonly afterWorkerLost: "orchestration-executions-settled-by-state-where-recovery-worker_lost";
+    readonly delegations: "orchestration-delegations-by-outcome";
+    readonly artifacts: "orchestration-artifacts-by-outcome";
+    readonly acceptance: "orchestration-acceptance_seconds-by-protocol";
+    readonly firstWorkerEvent: "orchestration-first_worker_event_seconds-by-protocol";
+    readonly conformancePassed: "orchestration-conformance-scenarios-by-binding-where-outcome-passed";
+    readonly conformanceFailed: "orchestration-conformance-scenarios-by-binding-where-outcome-failed";
+};
+/** A part of a whole, and the rate when there is a whole to divide by. */
+export interface Share {
+    part: number;
+    of: number;
+    /** `null` when nothing was counted, which is not the same as none. */
+    rate: number | null;
+}
+export interface OrchestrationMeasures {
+    /** Executions that lost sight of their worker, and how many completed. */
+    completedAfterDisconnect: Share;
+    /** Executions whose worker was lost, and how many completed anyway. */
+    completedAfterWorkerLost: Share;
+    /** Delegations, and how many repeated a command already received. */
+    duplicateDelegations: Share;
+    /** Artifacts a commit settled, and how many another attempt superseded. */
+    supersededArtifacts: Share;
+    /** Mean seconds from an execution's creation to its acceptance, by protocol. */
+    acceptanceSeconds: Record<string, number>;
+    /** Mean seconds from an execution's creation to its worker's first milestone, by protocol. */
+    firstWorkerEventSeconds: Record<string, number>;
+    /** Conformance scenarios run against each binding, and how many passed. */
+    conformance: Record<string, Share>;
+    /** The panels the service could not answer, by id, and why. */
+    unanswered: Record<string, string>;
+}
+/**
+ * The six measures, from the dashboard's answer.
+ *
+ * @param data - The orchestration dashboard, as `getDashboardData` returns it.
+ * @returns The measures, with the panels that did not answer named.
+ */
+export declare const orchestrationMeasures: (data: DashboardData) => OrchestrationMeasures;
+/**
+ * The six measures for the caller's account, or the one named.
+ *
+ * @param token - Authentication token.
+ * @param options - The window and the account to read as.
+ * @param otelUrl - The OTEL service.
+ * @returns The measures.
+ */
+export declare const fetchOrchestrationMeasures: (token: string, options?: DashboardDataOptions, otelUrl?: string) => Promise<OrchestrationMeasures>;

package/lib/api/orchestration/measures.js

@@ -0,0 +1,99 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/*
+ * Copyright (c) 2023-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * How delegated work is doing, read from the OTEL service's orchestration
+ * dashboard.
+ *
+ * Six measures: the share of executions that completed after losing sight
+ * of their worker, the share of delegations that were repeats and of
+ * artifacts that were superseded, the share that completed when the worker
+ * itself was lost, how long workers take to accept work and to report
+ * anything, and the share of the conformance scenarios each binding passes.
+ *
+ * The execution store records them wherever executions are held — the
+ * agents service, the durable service — under the account the executions
+ * belong to, and the service computes each panel from the series as they were
+ * exported. Nothing here adds metric points up: the panels arrive summarised,
+ * and this module only divides one panel's labels by another's. The panel ids
+ * are the dashboard's own, which a contract test in the OTEL service holds to
+ * the ones named here.
+ *
+ * @module api/orchestration/measures
+ */
+import { DEFAULT_SERVICE_URLS } from '../constants.js';
+import { getDashboardData, } from '../otel/dashboards.js';
+/** The built-in dashboard the measures are read from. */
+export const ORCHESTRATION_DASHBOARD = 'orchestration';
+/** The panels each measure is read from, by the dashboard's ids. */
+export const ORCHESTRATION_PANELS = {
+    afterDisconnect: 'orchestration-executions-settled-by-state-where-recovery-disconnected',
+    afterWorkerLost: 'orchestration-executions-settled-by-state-where-recovery-worker_lost',
+    delegations: 'orchestration-delegations-by-outcome',
+    artifacts: 'orchestration-artifacts-by-outcome',
+    acceptance: 'orchestration-acceptance_seconds-by-protocol',
+    firstWorkerEvent: 'orchestration-first_worker_event_seconds-by-protocol',
+    conformancePassed: 'orchestration-conformance-scenarios-by-binding-where-outcome-passed',
+    conformanceFailed: 'orchestration-conformance-scenarios-by-binding-where-outcome-failed',
+};
+const share = (part, of) => ({
+    part,
+    of,
+    rate: of > 0 ? part / of : null,
+});
+/**
+ * The six measures, from the dashboard's answer.
+ *
+ * @param data - The orchestration dashboard, as `getDashboardData` returns it.
+ * @returns The measures, with the panels that did not answer named.
+ */
+export const orchestrationMeasures = (data) => {
+    const panels = new Map(data.panels.map(panel => [panel.id, panel]));
+    const unanswered = {};
+    const byLabel = (id) => {
+        const panel = panels.get(id);
+        if (!panel || panel.error) {
+            unanswered[id] = panel?.error ?? 'The dashboard has no such panel.';
+            return {};
+        }
+        return Object.fromEntries(panel.series
+            .filter(entry => entry.summary !== null)
+            .map(entry => [entry.label, entry.summary]));
+    };
+    const total = (values) => Object.values(values).reduce((sum, value) => sum + value, 0);
+    const afterDisconnect = byLabel(ORCHESTRATION_PANELS.afterDisconnect);
+    const afterWorkerLost = byLabel(ORCHESTRATION_PANELS.afterWorkerLost);
+    const delegations = byLabel(ORCHESTRATION_PANELS.delegations);
+    const artifacts = byLabel(ORCHESTRATION_PANELS.artifacts);
+    const passed = byLabel(ORCHESTRATION_PANELS.conformancePassed);
+    const failed = byLabel(ORCHESTRATION_PANELS.conformanceFailed);
+    const conformance = {};
+    for (const binding of new Set([...Object.keys(passed), ...Object.keys(failed)])) {
+        const ok = passed[binding] ?? 0;
+        conformance[binding] = share(ok, ok + (failed[binding] ?? 0));
+    }
+    return {
+        completedAfterDisconnect: share(afterDisconnect.completed ?? 0, total(afterDisconnect)),
+        completedAfterWorkerLost: share(afterWorkerLost.completed ?? 0, total(afterWorkerLost)),
+        duplicateDelegations: share(delegations.duplicate ?? 0, total(delegations)),
+        supersededArtifacts: share(artifacts.superseded ?? 0, total(artifacts)),
+        acceptanceSeconds: byLabel(ORCHESTRATION_PANELS.acceptance),
+        firstWorkerEventSeconds: byLabel(ORCHESTRATION_PANELS.firstWorkerEvent),
+        conformance,
+        unanswered,
+    };
+};
+/**
+ * The six measures for the caller's account, or the one named.
+ *
+ * @param token - Authentication token.
+ * @param options - The window and the account to read as.
+ * @param otelUrl - The OTEL service.
+ * @returns The measures.
+ */
+export const fetchOrchestrationMeasures = async (token, options = {}, otelUrl = DEFAULT_SERVICE_URLS.OTEL) => orchestrationMeasures(await getDashboardData(token, ORCHESTRATION_DASHBOARD, options, otelUrl));

package/lib/api/otel/dashboards.d.ts

@@ -0,0 +1,56 @@
+/** What one export of a series added, for a chart. */
+export interface DashboardPoint {
+    /** Unix nanoseconds, which a JavaScript number holds only approximately. */
+    t: number;
+    v: number;
+}
+/** One label value of a panel: its series combined one way. */
+export interface DashboardSeries {
+    label: string;
+    /** `null` when there was nothing to divide by, as for a duration never measured. */
+    summary: number | null;
+    /** How many series (processes, attribute sets) the summary combines. */
+    series: number;
+    points: DashboardPoint[];
+}
+/** One panel and its answer. */
+export interface DashboardPanelData {
+    id: string;
+    title: string;
+    metric: string;
+    by: string | null;
+    where: Record<string, string>;
+    agg: string;
+    kind: string;
+    series: DashboardSeries[];
+    /** The limit cut the points a chart draws; the summaries are whole. */
+    points_truncated?: boolean;
+    /** Why the service could not answer this panel; the others still answer. */
+    error?: string;
+}
+/** A dashboard's every panel, answered under one account. */
+export interface DashboardData {
+    success: boolean;
+    id: string;
+    title: string;
+    account_uid: string;
+    panels: DashboardPanelData[];
+}
+export interface DashboardDataOptions {
+    /** The window opens here; all of the retained history without it. */
+    since?: Date;
+    /** The window closes here; now without it. */
+    until?: Date;
+    /** Read as this organization or team rather than the caller. */
+    accountUid?: string;
+}
+/**
+ * Every panel of one dashboard, answered under the caller's account scope.
+ *
+ * @param token - Authentication token.
+ * @param dashboardId - A built-in dashboard's id, or one the account saved.
+ * @param options - The window and the account to read as.
+ * @param baseUrl - The OTEL service.
+ * @returns The panels and their summaries.
+ */
+export declare const getDashboardData: (token: string, dashboardId: string, options?: DashboardDataOptions, baseUrl?: string) => Promise<DashboardData>;

package/lib/api/otel/dashboards.js

@@ -0,0 +1,50 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/*
+ * Copyright (c) 2023-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * OTEL dashboards, read under an account.
+ *
+ * A panel's numbers come back computed by the OTEL service, which reads
+ * each series the way it was exported: a running total's increase over the
+ * window, a level's latest reading, a duration's total over its count.
+ * Services export counters as running totals, so adding raw metric points up
+ * counts every earlier report again; a view reads these summaries instead.
+ *
+ * @module api/otel/dashboards
+ */
+import { requestDatalayerAPI } from '../DatalayerApi.js';
+import { API_BASE_PATHS, DEFAULT_SERVICE_URLS } from '../constants.js';
+import { validateToken } from '../utils/validation.js';
+/** A date as the unix nanoseconds the service takes, spelled exactly. */
+const nanoseconds = (date) => `${Math.floor(date.getTime())}000000`;
+/**
+ * Every panel of one dashboard, answered under the caller's account scope.
+ *
+ * @param token - Authentication token.
+ * @param dashboardId - A built-in dashboard's id, or one the account saved.
+ * @param options - The window and the account to read as.
+ * @param baseUrl - The OTEL service.
+ * @returns The panels and their summaries.
+ */
+export const getDashboardData = async (token, dashboardId, options = {}, baseUrl = DEFAULT_SERVICE_URLS.OTEL) => {
+    validateToken(token);
+    const params = new URLSearchParams();
+    if (options.since)
+        params.set('start', nanoseconds(options.since));
+    if (options.until)
+        params.set('end', nanoseconds(options.until));
+    if (options.accountUid)
+        params.set('account_uid', options.accountUid);
+    const queryString = params.toString();
+    const url = `${baseUrl}${API_BASE_PATHS.OTEL}/dashboards/${encodeURIComponent(dashboardId)}/data${queryString ? `?${queryString}` : ''}`;
+    return requestDatalayerAPI({
+        url,
+        method: 'GET',
+        token,
+    });
+};

package/lib/api/otel/index.d.ts

@@ -10,3 +10,4 @@ export * as metrics from './metrics';
 export * as logs from './logs';
 export * as services from './services';
 export * as query from './query';
+export * as dashboards from './dashboards';

package/lib/api/otel/index.js

@@ -14,3 +14,4 @@ export * as metrics from './metrics.js';
 export * as logs from './logs.js';
 export * as services from './services.js';
 export * as query from './query.js';
+export * as dashboards from './dashboards.js';

package/lib/api/otel/metrics.d.ts

@@ -13,6 +13,22 @@ export declare const listMetrics: (token: string, options?: {
     serviceName?: string;
     limit?: number;
 }, baseUrl?: string) => Promise<ListMetricsResponse>;
+/** One metric the OTEL service holds points of. */
+export interface MetricName {
+    metric_name: string;
+    metric_type?: string;
+    metric_unit?: string;
+}
+/**
+ * The metrics the OTEL service holds points of, under the caller's account.
+ *
+ * @param token - Authentication token
+ * @param baseUrl - Base URL for the OTEL service
+ * @returns Promise resolving to the distinct metric names
+ */
+export declare const listMetricNames: (token: string, baseUrl?: string) => Promise<{
+    data: MetricName[];
+}>;
 /**
  * Query metric data points with filters.
  *

package/lib/api/otel/metrics.js

@@ -35,6 +35,21 @@ export const listMetrics = async (token, options = {}, baseUrl = DEFAULT_SERVICE
         token,
     });
 };
+/**
+ * The metrics the OTEL service holds points of, under the caller's account.
+ *
+ * @param token - Authentication token
+ * @param baseUrl - Base URL for the OTEL service
+ * @returns Promise resolving to the distinct metric names
+ */
+export const listMetricNames = async (token, baseUrl = DEFAULT_SERVICE_URLS.OTEL) => {
+    validateToken(token);
+    return requestDatalayerAPI({
+        url: `${baseUrl}${API_BASE_PATHS.OTEL}/metrics/names`,
+        method: 'GET',
+        token,
+    });
+};
 /**
  * Query metric data points with filters.
  *

package/lib/api/scheduler/client.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The Scheduler API, one function per endpoint this UI uses.
+ *
+ * Paths mirror `datalayer_scheduler/api/v1/endpoints/schedules.py`. Only
+ * the routes a schedule's own management needs are wrapped here — the
+ * notebook-run reading and reporting routes `views/schedules/Schedules.tsx`
+ * already reaches directly stay as they are.
+ *
+ * @module api/scheduler/client
+ */
+import { type SchedulerClientOptions } from './request';
+import type { ScheduleListResponse, ScheduleResponse, ScheduleRunListResponse, UpdateScheduleRequest, UpsertScheduleRequest } from './types';
+/** Every schedule the caller owns, `notebook` and `evalset` alike. */
+export declare const listSchedules: (options: SchedulerClientOptions, query?: {
+    includeDisabled?: boolean;
+}) => Promise<ScheduleListResponse>;
+/** One schedule. */
+export declare const getSchedule: (options: SchedulerClientOptions, scheduleUid: string) => Promise<ScheduleResponse>;
+/**
+ * Create the one schedule a target has, or replace it (BENCHMARK.md, B2-16):
+ * a schedule is unique per owner and target, so upserting is how a person
+ * changes an `evalset` schedule's cron or configuration too.
+ */
+export declare const upsertSchedule: (options: SchedulerClientOptions, body: UpsertScheduleRequest) => Promise<ScheduleResponse>;
+/** Change a schedule's cron expression, preset or enabled flag. */
+export declare const updateSchedule: (options: SchedulerClientOptions, scheduleUid: string, body: UpdateScheduleRequest) => Promise<ScheduleResponse>;
+/** Turn a schedule off, without losing its cron and configuration. */
+export declare const disableSchedule: (options: SchedulerClientOptions, scheduleUid: string) => Promise<ScheduleResponse>;
+/** The runs of one schedule, newest first. */
+export declare const listScheduleRuns: (options: SchedulerClientOptions, scheduleUid: string) => Promise<ScheduleRunListResponse>;
+/** Every run of every schedule the caller owns, newest first. */
+export declare const listAllScheduleRuns: (options: SchedulerClientOptions) => Promise<ScheduleRunListResponse>;

package/lib/api/scheduler/client.js

@@ -0,0 +1,42 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/*
+ * Copyright (c) 2023-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * The Scheduler API, one function per endpoint this UI uses.
+ *
+ * Paths mirror `datalayer_scheduler/api/v1/endpoints/schedules.py`. Only
+ * the routes a schedule's own management needs are wrapped here — the
+ * notebook-run reading and reporting routes `views/schedules/Schedules.tsx`
+ * already reaches directly stay as they are.
+ *
+ * @module api/scheduler/client
+ */
+import { schedulerRequest, scheduleSegment, } from './request.js';
+/** Every schedule the caller owns, `notebook` and `evalset` alike. */
+export const listSchedules = (options, query = {}) => schedulerRequest(options, '/schedules', {
+    query: { includeDisabled: query.includeDisabled },
+});
+/** One schedule. */
+export const getSchedule = (options, scheduleUid) => schedulerRequest(options, `/schedules/${scheduleSegment(scheduleUid)}`);
+/**
+ * Create the one schedule a target has, or replace it (BENCHMARK.md, B2-16):
+ * a schedule is unique per owner and target, so upserting is how a person
+ * changes an `evalset` schedule's cron or configuration too.
+ */
+export const upsertSchedule = (options, body) => schedulerRequest(options, '/schedules', {
+    method: 'POST',
+    body,
+});
+/** Change a schedule's cron expression, preset or enabled flag. */
+export const updateSchedule = (options, scheduleUid, body) => schedulerRequest(options, `/schedules/${scheduleSegment(scheduleUid)}`, { method: 'PUT', body });
+/** Turn a schedule off, without losing its cron and configuration. */
+export const disableSchedule = (options, scheduleUid) => schedulerRequest(options, `/schedules/${scheduleSegment(scheduleUid)}/disable`, { method: 'POST' });
+/** The runs of one schedule, newest first. */
+export const listScheduleRuns = (options, scheduleUid) => schedulerRequest(options, `/schedules/${scheduleSegment(scheduleUid)}/runs`);
+/** Every run of every schedule the caller owns, newest first. */
+export const listAllScheduleRuns = (options) => schedulerRequest(options, '/schedules/runs');

package/lib/api/scheduler/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The Scheduler API: what runs on a cron, and what it produced.
+ *
+ * @module api/scheduler
+ */
+export * from './types';
+export * from './request';
+export * from './client';

package/lib/api/scheduler/index.js

@@ -0,0 +1,16 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/*
+ * Copyright (c) 2023-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * The Scheduler API: what runs on a cron, and what it produced.
+ *
+ * @module api/scheduler
+ */
+export * from './types.js';
+export * from './request.js';
+export * from './client.js';

package/lib/api/scheduler/request.d.ts

@@ -0,0 +1,28 @@
+/** What every Scheduler call needs to know. */
+export interface SchedulerClientOptions {
+    /** The Scheduler service origin, e.g. `https://prod1.datalayer.run`. */
+    baseUrl?: string;
+    /** The caller's IAM token. */
+    token?: string;
+}
+export type SchedulerQuery = Record<string, string | number | boolean | undefined | null>;
+export interface SchedulerRequestInit {
+    method?: 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE';
+    body?: unknown;
+    query?: SchedulerQuery;
+    signal?: AbortSignal;
+}
+/** The Scheduler origin, with no trailing slash. */
+export declare const schedulerOrigin: (baseUrl?: string) => string;
+/**
+ * A full URL under `/api/scheduler/v1`, with the query merged in. Empty,
+ * null and undefined values are left out.
+ */
+export declare const schedulerUrl: (options: SchedulerClientOptions, path: string, query?: SchedulerQuery) => string;
+/**
+ * One request to the Scheduler service, `path` relative to
+ * `/api/scheduler/v1`.
+ */
+export declare const schedulerRequest: <T>(options: SchedulerClientOptions, path: string, init?: SchedulerRequestInit) => Promise<T>;
+/** A path segment, encoded once. */
+export declare const scheduleSegment: (value: string) => string;