@datalayer/core 1.1.66 → 1.2.10

package/lib/api/scheduler/request.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.
+ */
+/**
+ * How the Scheduler API is reached.
+ *
+ * The origin, the `/api/scheduler/v1` prefix and the caller's credential in
+ * one place, as `api/evals/request` holds them for the AI Agents service.
+ *
+ * @module api/scheduler/request
+ */
+import { requestDatalayerAPI } from '../DatalayerApi.js';
+import { API_BASE_PATHS, DEFAULT_SERVICE_URLS } from '../constants.js';
+/** The Scheduler origin, with no trailing slash. */
+export const schedulerOrigin = (baseUrl) => String(baseUrl || DEFAULT_SERVICE_URLS.SCHEDULER)
+    .trim()
+    .replace(/\/+$/, '');
+/**
+ * A full URL under `/api/scheduler/v1`, with the query merged in. Empty,
+ * null and undefined values are left out.
+ */
+export const schedulerUrl = (options, path, query = {}) => {
+    const [pathname, inlineSearch = ''] = path.split('?');
+    const parameters = new URLSearchParams(inlineSearch);
+    for (const [key, value] of Object.entries(query)) {
+        if (value !== undefined && value !== null && value !== '') {
+            parameters.set(key, String(value));
+        }
+    }
+    const search = parameters.toString();
+    return `${schedulerOrigin(options.baseUrl)}${API_BASE_PATHS.SCHEDULER}${pathname}${search ? `?${search}` : ''}`;
+};
+/**
+ * One request to the Scheduler service, `path` relative to
+ * `/api/scheduler/v1`.
+ */
+export const schedulerRequest = (options, path, init = {}) => requestDatalayerAPI({
+    url: schedulerUrl(options, path, init.query),
+    method: init.method ?? 'GET',
+    body: init.body,
+    token: options.token,
+    signal: init.signal,
+});
+/** A path segment, encoded once. */
+export const scheduleSegment = (value) => encodeURIComponent(String(value ?? '').trim());

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

@@ -0,0 +1,88 @@
+/**
+ * The Scheduler API's own shapes.
+ *
+ * A schedule and a schedule run are Solr documents the service answers
+ * as they are stored — field suffixes and all — rather than a projection:
+ * `views/schedules/Schedules.tsx` has always read them this way, and these
+ * types describe that wire shape rather than inventing a cleaner one the
+ * service does not actually send.
+ *
+ * @module api/scheduler/types
+ */
+/** What a schedule runs. `notebook` is every schedule from before B2-16. */
+export type ScheduleTargetKind = 'notebook' | 'evalset';
+/** One schedule, as the service answers it. */
+export interface ScheduleRecord {
+    uid: string;
+    owner_uid_s: string;
+    owner_handle_s?: string;
+    owner_display_name_s?: string;
+    principal_kind_s?: string;
+    billing_entity_uid_s?: string;
+    target_kind_s: ScheduleTargetKind | string;
+    /** The evalset id or, for a notebook schedule, the notebook uid. */
+    target_uid_s: string;
+    /** Set only for a notebook schedule. */
+    notebook_uid_s?: string;
+    cron_expression_s: string;
+    preset_s: string;
+    enabled_b: boolean;
+    /** What the target is run with, as JSON text — parse with `scheduleConfigOf`. */
+    config_json_t?: string;
+    next_planned_ts_dt?: string;
+    creation_ts_dt?: string;
+    last_update_ts_dt?: string;
+}
+/** What an `evalset` schedule's `config_json_t` holds (BENCHMARK.md, B2-16). */
+export interface EvalsetScheduleConfig {
+    /** Empty means every live experiment of the evalset, resolved at run time. */
+    experiment_ids?: string[];
+    run_mode?: 'batch' | 'interactive';
+    config?: Record<string, unknown>;
+}
+export type ScheduleRunState = 'planned' | 'running' | 'dispatched' | 'executed' | 'executed_with_failure' | 'failed';
+/** One run of a schedule, as the service answers it. */
+export interface ScheduleRunRecord {
+    uid: string;
+    schedule_uid_s: string;
+    owner_uid_s: string;
+    target_kind_s: ScheduleTargetKind | string;
+    target_uid_s: string;
+    notebook_uid_s?: string;
+    state_s: ScheduleRunState | string;
+    success_b?: boolean | null;
+    result_s?: string;
+    planned_ts_dt?: string;
+    executed_ts_dt?: string;
+    last_update_ts_dt?: string;
+}
+export interface ScheduleListResponse {
+    success: boolean;
+    message: string;
+    schedules: ScheduleRecord[];
+}
+export interface ScheduleResponse {
+    success: boolean;
+    message: string;
+    schedule: ScheduleRecord;
+}
+export interface ScheduleRunListResponse {
+    success: boolean;
+    message: string;
+    runs: ScheduleRunRecord[];
+}
+/** `POST /schedules`: create, or replace the one schedule a target has. */
+export interface UpsertScheduleRequest {
+    targetUid: string;
+    targetKind?: ScheduleTargetKind;
+    cronExpression: string;
+    preset?: string;
+    enabled?: boolean;
+    config?: EvalsetScheduleConfig;
+}
+/** `PUT /schedules/{uid}`: change one field or more of an existing schedule. */
+export interface UpdateScheduleRequest {
+    cronExpression?: string;
+    preset?: string;
+    enabled?: boolean;
+}

package/lib/api/scheduler/types.js

@@ -0,0 +1,5 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+export {};

package/lib/api/spacer/comments.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Comments on documents and notebooks (BENCHMARK.md, B4-01).
+ *
+ * A thread is its first comment, about one anchor — the highlighted text, a
+ * report's evidence block, a cell, a task, a data point — and a reply names
+ * its thread. The comments of an item are read and written on the item's
+ * route, changed and settled on the comment's, and followed on a websocket
+ * that says `subscribed` once it listens and then each comment written.
+ *
+ * @module api/spacer/comments
+ */
+import { type SpacerClientOptions } from './request';
+export type CommentItemType = 'lexical' | 'notebook';
+export type CommentAnchorKind = 'mark_id' | 'block_id' | 'cell_id' | 'case_id' | 'datum';
+/** What a thread is about: exactly one kind. */
+export type CommentAnchor = Partial<Record<CommentAnchorKind, string>>;
+export type CommentStatus = 'open' | 'resolved';
+export interface SpacerComment {
+    uid: string;
+    item_uid: string;
+    item_type: CommentItemType;
+    /** The uid of the thread's first comment; that comment's own. */
+    thread_uid: string;
+    /** A thread's; `null` on a reply. */
+    anchor: CommentAnchor | null;
+    quote: string | null;
+    /** Empty once deleted. */
+    body: string;
+    author: SpacerCommentPerson;
+    mentions: string[];
+    /** A thread's; `null` on a reply and on a thread nobody is assigned. */
+    assignee: SpacerCommentPerson | null;
+    /** The page a thread is read on; `null` on a reply. */
+    link: string | null;
+    /** A thread's; `null` on a reply. */
+    status: CommentStatus | null;
+    resolution: string | null;
+    resolved_by_uid: string | null;
+    resolved_at: string | null;
+    deleted: boolean;
+    created_at: string;
+    updated_at: string;
+}
+/** Somebody a comment names: its author, a thread's assignee. */
+export interface SpacerCommentPerson {
+    uid: string;
+    handle: string | null;
+    name: string | null;
+    /** On an author: the agent that wrote the comment for them, when one did. */
+    agent_uid?: string;
+}
+export interface AddCommentRequest {
+    body: string;
+    /** A new thread's. */
+    anchor?: CommentAnchor;
+    quote?: string;
+    /**
+     * The page a new thread is read on, a path of the app: where a mention or
+     * an assignment sends the person it names.
+     */
+    link?: string;
+    /** A reply's thread. */
+    thread_uid?: string;
+    mentions?: string[];
+    assignee_uid?: string;
+}
+/** What is named changes; `assignee_uid: null` unassigns. */
+export interface UpdateCommentRequest {
+    body?: string;
+    mentions?: string[];
+    assignee_uid?: string | null;
+    deleted?: true;
+}
+export interface CommentsResponse {
+    success: boolean;
+    comments: SpacerComment[];
+}
+export interface CommentResponse {
+    success: boolean;
+    comment: SpacerComment;
+}
+export type CommentsChannelMessage = {
+    type: 'subscribed';
+    item_uid: string;
+} | {
+    type: 'comment';
+    comment: SpacerComment;
+};
+/** An item's comments in the order written, deleted ones in their place. */
+export declare const listComments: (options: SpacerClientOptions, itemType: CommentItemType, itemUid: string, status?: CommentStatus) => Promise<CommentsResponse>;
+/** Open a thread on an item, or reply in one of its threads. */
+export declare const addComment: (options: SpacerClientOptions, itemType: CommentItemType, itemUid: string, body: AddCommentRequest) => Promise<CommentResponse>;
+export declare const updateComment: (options: SpacerClientOptions, uid: string, body: UpdateCommentRequest) => Promise<CommentResponse>;
+export declare const resolveComment: (options: SpacerClientOptions, uid: string, resolution?: string) => Promise<CommentResponse>;
+export declare const reopenComment: (options: SpacerClientOptions, uid: string) => Promise<CommentResponse>;
+/** The websocket an item's comments are followed on, carrying the token. */
+export declare const commentsChannelUrl: (options: SpacerClientOptions, itemUid: string) => string;

package/lib/api/spacer/comments.js

@@ -0,0 +1,45 @@
+/*
+ * 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.
+ */
+/**
+ * Comments on documents and notebooks (BENCHMARK.md, B4-01).
+ *
+ * A thread is its first comment, about one anchor — the highlighted text, a
+ * report's evidence block, a cell, a task, a data point — and a reply names
+ * its thread. The comments of an item are read and written on the item's
+ * route, changed and settled on the comment's, and followed on a websocket
+ * that says `subscribed` once it listens and then each comment written.
+ *
+ * @module api/spacer/comments
+ */
+import { spacerRequest, spacerSegment, spacerUrl, } from './request.js';
+const itemComments = (itemType, itemUid) => `/${itemType === 'lexical' ? 'lexicals' : 'notebooks'}/${spacerSegment(itemUid)}/comments`;
+/** An item's comments in the order written, deleted ones in their place. */
+export const listComments = (options, itemType, itemUid, status) => spacerRequest(options, itemComments(itemType, itemUid), {
+    query: { status },
+});
+/** Open a thread on an item, or reply in one of its threads. */
+export const addComment = (options, itemType, itemUid, body) => spacerRequest(options, itemComments(itemType, itemUid), {
+    method: 'POST',
+    body,
+});
+export const updateComment = (options, uid, body) => spacerRequest(options, `/comments/${spacerSegment(uid)}`, {
+    method: 'PATCH',
+    body,
+});
+export const resolveComment = (options, uid, resolution) => spacerRequest(options, `/comments/${spacerSegment(uid)}/resolve`, {
+    method: 'POST',
+    body: resolution ? { resolution } : {},
+});
+export const reopenComment = (options, uid) => spacerRequest(options, `/comments/${spacerSegment(uid)}/reopen`, {
+    method: 'POST',
+});
+/** The websocket an item's comments are followed on, carrying the token. */
+export const commentsChannelUrl = (options, itemUid) => spacerUrl(options, `/comments/ws/${spacerSegment(itemUid)}`, {
+    token: options.token,
+}).replace(/^http/, 'ws');

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

@@ -0,0 +1,9 @@
+/**
+ * The Spacer API: documents, notebooks and what is said about them.
+ *
+ * @module api/spacer
+ */
+export * from './request';
+export * from './comments';
+export * from './spaces';
+export * from './notebooks';

package/lib/api/spacer/index.js

@@ -0,0 +1,17 @@
+/*
+ * 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 Spacer API: documents, notebooks and what is said about them.
+ *
+ * @module api/spacer
+ */
+export * from './request.js';
+export * from './comments.js';
+export * from './spaces.js';
+export * from './notebooks.js';

package/lib/api/spacer/notebooks.d.ts

@@ -0,0 +1,33 @@
+/**
+ * A notebook's content, read by its uid.
+ *
+ * What a view needs when it shows a notebook it did not open — the outputs of
+ * a notebook an agent produced, previewed in its execution's report — without
+ * starting an editor or a kernel.
+ *
+ * @module api/spacer/notebooks
+ */
+import { type SpacerClientOptions } from './request';
+/** One cell, as nbformat writes it. */
+export interface NotebookCell {
+    cell_type: string;
+    source?: string | string[];
+    outputs?: Array<Record<string, unknown>>;
+    metadata?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+/** A notebook, as nbformat writes it. */
+export interface NotebookModel {
+    cells: NotebookCell[];
+    metadata?: Record<string, unknown>;
+    nbformat?: number;
+    nbformat_minor?: number;
+}
+/**
+ * The notebook's content, or `undefined` when Spacer holds none that parses.
+ *
+ * @param options - The Spacer origin and the caller's token.
+ * @param notebookUid - The notebook.
+ * @returns The notebook's model.
+ */
+export declare const getNotebookModel: (options: SpacerClientOptions, notebookUid: string) => Promise<NotebookModel | undefined>;

package/lib/api/spacer/notebooks.js

@@ -0,0 +1,39 @@
+/*
+ * 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.
+ */
+/**
+ * A notebook's content, read by its uid.
+ *
+ * What a view needs when it shows a notebook it did not open — the outputs of
+ * a notebook an agent produced, previewed in its execution's report — without
+ * starting an editor or a kernel.
+ *
+ * @module api/spacer/notebooks
+ */
+import { spacerRequest, spacerSegment, } from './request.js';
+/**
+ * The notebook's content, or `undefined` when Spacer holds none that parses.
+ *
+ * @param options - The Spacer origin and the caller's token.
+ * @param notebookUid - The notebook.
+ * @returns The notebook's model.
+ */
+export const getNotebookModel = async (options, notebookUid) => {
+    const answer = await spacerRequest(options, `/notebooks/${spacerSegment(notebookUid)}`);
+    const raw = answer.notebook?.model_s;
+    if (!raw) {
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        return parsed && Array.isArray(parsed.cells) ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};

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

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

package/lib/api/spacer/request.js

@@ -0,0 +1,46 @@
+/*
+ * 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 the Spacer API is reached.
+ *
+ * The origin, the `/api/spacer/v1` prefix and the caller's credential in one
+ * place, as `api/evals/request` holds them for the AI Agents service.
+ *
+ * @module api/spacer/request
+ */
+import { requestDatalayerAPI } from '../DatalayerApi.js';
+import { API_BASE_PATHS, DEFAULT_SERVICE_URLS } from '../constants.js';
+/** The Spacer origin, with no trailing slash. */
+export const spacerOrigin = (baseUrl) => String(baseUrl || DEFAULT_SERVICE_URLS.SPACER)
+    .trim()
+    .replace(/\/+$/, '');
+/**
+ * A full URL under `/api/spacer/v1`, with the query merged in. Empty, null
+ * and undefined values are left out.
+ */
+export const spacerUrl = (options, path, query = {}) => {
+    const parameters = new URLSearchParams();
+    for (const [key, value] of Object.entries(query)) {
+        if (value !== undefined && value !== null && value !== '') {
+            parameters.set(key, String(value));
+        }
+    }
+    const search = parameters.toString();
+    return `${spacerOrigin(options.baseUrl)}${API_BASE_PATHS.SPACER}${path}${search ? `?${search}` : ''}`;
+};
+/** One request to Spacer, `path` relative to `/api/spacer/v1`. */
+export const spacerRequest = (options, path, init = {}) => requestDatalayerAPI({
+    url: spacerUrl(options, path, init.query),
+    method: init.method ?? 'GET',
+    body: init.body,
+    token: options.token,
+    signal: init.signal,
+});
+/** A path segment, encoded once. */
+export const spacerSegment = (value) => encodeURIComponent(String(value ?? '').trim());

package/lib/api/spacer/spaces.d.ts

@@ -0,0 +1,68 @@
+/**
+ * An account's managed spaces: the benchmarks space, where a launch's reports
+ * and evidence are written, and the orchestration space, where what agents
+ * produced for the account's executions is written.
+ *
+ * One of each per account — the person, or an organization or a team they
+ * belong to — made by Spacer on first use, following the account's membership
+ * and never offered in the create flow. The answer names the two path
+ * segments the app opens an object of the space under:
+ * `/{account_handle}/{handle}/documents/{uid}`.
+ *
+ * @module api/spacer/spaces
+ */
+import { type SpacerClientOptions } from './request';
+export type ManagedSpaceKind = 'benchmarks' | 'orchestration';
+export interface ManagedSpace {
+    uid: string;
+    id?: string;
+    handle: string;
+    name: string;
+    variant: string;
+    account_uid: string;
+    account_type: 'user' | 'organization' | 'team';
+    /** The handle of the account the space belongs to, as the app's paths start. */
+    account_handle: string;
+    organization_uid?: string;
+    team_uid?: string;
+}
+/**
+ * An account's managed space of a kind, made by Spacer on first use.
+ *
+ * @param options - The Spacer origin and the caller's token.
+ * @param kind - `benchmarks` or `orchestration`.
+ * @param accountUid - The organization or team; the caller when omitted.
+ * @returns The space.
+ */
+export declare const getManagedSpace: (options: SpacerClientOptions, kind: ManagedSpaceKind, accountUid?: string) => Promise<ManagedSpace>;
+/** One item of somebody's workspace, as Spacer answers it. */
+export interface WorkspaceItem {
+    uid: string;
+    type_s?: string;
+    name_t?: string;
+    description_t?: string;
+    notebook_name_s?: string;
+    document_name_s?: string;
+    creator_handle_s?: string;
+    space_uid?: string;
+    last_update_ts_dt?: string;
+    [key: string]: unknown;
+}
+export interface WorkspaceSearchResponse {
+    success: boolean;
+    message?: string;
+    items: WorkspaceItem[];
+}
+/**
+ * Search the caller's own workspace: notebooks, documents, datasets, files
+ * (BENCHMARKS.md, B5-11, section 19).
+ *
+ * Scoped by the service to what this person may open — never other people's
+ * public items, which the Library's own search answers. An empty query lists
+ * what the scope allows.
+ */
+export declare const searchWorkspace: (options: SpacerClientOptions, query?: {
+    q?: string;
+    types?: string;
+    max?: number;
+}) => Promise<WorkspaceSearchResponse>;

package/lib/api/spacer/spaces.js

@@ -0,0 +1,45 @@
+/*
+ * 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.
+ */
+/**
+ * An account's managed spaces: the benchmarks space, where a launch's reports
+ * and evidence are written, and the orchestration space, where what agents
+ * produced for the account's executions is written.
+ *
+ * One of each per account — the person, or an organization or a team they
+ * belong to — made by Spacer on first use, following the account's membership
+ * and never offered in the create flow. The answer names the two path
+ * segments the app opens an object of the space under:
+ * `/{account_handle}/{handle}/documents/{uid}`.
+ *
+ * @module api/spacer/spaces
+ */
+import { spacerRequest, spacerSegment, } from './request.js';
+/**
+ * An account's managed space of a kind, made by Spacer on first use.
+ *
+ * @param options - The Spacer origin and the caller's token.
+ * @param kind - `benchmarks` or `orchestration`.
+ * @param accountUid - The organization or team; the caller when omitted.
+ * @returns The space.
+ */
+export const getManagedSpace = async (options, kind, accountUid) => {
+    const answer = await spacerRequest(options, `/spaces/${spacerSegment(kind)}`, { query: { account_uid: accountUid } });
+    return answer.space;
+};
+/**
+ * Search the caller's own workspace: notebooks, documents, datasets, files
+ * (BENCHMARKS.md, B5-11, section 19).
+ *
+ * Scoped by the service to what this person may open — never other people's
+ * public items, which the Library's own search answers. An empty query lists
+ * what the scope allows.
+ */
+export const searchWorkspace = (options, query = {}) => spacerRequest(options, '/spaces/items/search', {
+    query,
+});

package/lib/api/utils/validation.d.ts

@@ -15,7 +15,7 @@ export declare const validateToken: (token: string | undefined | null) => void;
  * @param paramName - The name of the parameter for error messages
  * @throws {Error} If the value is missing, null, or undefined
  */
-export declare const validateRequired: (value: any, paramName: string) => void;
+export declare const validateRequired: (value: unknown, paramName: string) => void;
 /**
  * Validates that a string parameter is provided and not empty
  * @param value - The string value to validate
@@ -36,12 +36,12 @@ export declare const validateRequiredString: (value: string | undefined | null,
  * @example
  * ```typescript
  * const runtimeData = {
- *   uid: 'abc123',
- *   runtimeName: 'runtime-abc123',
+ *   uid: '01m1dzmb1anqzp1v1ng97x7214',
+ *   runtimeName: '01m1dzmb1anqzp1v1ng97x7214',
  *   environmentName: undefined  // This will throw
  * };
  * validateJSON(runtimeData, 'Runtime');
  * // Error: Runtime.toJSON(): Property 'environmentName' is undefined
  * ```
  */
-export declare const validateJSON: (obj: Record<string, any>, modelName: string, path?: string) => void;
+export declare const validateJSON: (obj: object, modelName: string, path?: string) => void;

package/lib/api/utils/validation.js

@@ -66,7 +66,7 @@ export const validateToken = (token) => {
             e.message === 'Invalid token format: Missing algorithm in JWT header') {
             throw e;
         }
-        throw new Error('Invalid token format: JWT header is not valid base64-encoded JSON');
+        throw new Error('Invalid token format: JWT header is not valid base64-encoded JSON', { cause: e });
     }
     // Validate payload structure (should be valid base64url JSON)
     try {
@@ -103,7 +103,7 @@ export const validateToken = (token) => {
                 e.message === 'Token is not yet valid')) {
             throw e;
         }
-        throw new Error('Invalid token format: JWT payload is not valid base64-encoded JSON');
+        throw new Error('Invalid token format: JWT payload is not valid base64-encoded JSON', { cause: e });
     }
     // Signature part validation (just check it exists and has reasonable length)
     if (parts[2].length < 20) {
@@ -145,8 +145,8 @@ export const validateRequiredString = (value, paramName) => {
  * @example
  * ```typescript
  * const runtimeData = {
- *   uid: 'abc123',
- *   runtimeName: 'runtime-abc123',
+ *   uid: '01m1dzmb1anqzp1v1ng97x7214',
+ *   runtimeName: '01m1dzmb1anqzp1v1ng97x7214',
  *   environmentName: undefined  // This will throw
  * };
  * validateJSON(runtimeData, 'Runtime');
@@ -154,12 +154,15 @@ export const validateRequiredString = (value, paramName) => {
  * ```
  */
 export const validateJSON = (obj, modelName, path = '') => {
+    // Any object: a model's JSON is an interface without an index signature,
+    // and an interface is not a `Record` — it is read as one here.
+    const record = obj;
     // Iterate over all enumerable properties
-    for (const key in obj) {
-        if (!Object.prototype.hasOwnProperty.call(obj, key)) {
+    for (const key in record) {
+        if (!Object.prototype.hasOwnProperty.call(record, key)) {
             continue;
         }
-        const value = obj[key];
+        const value = record[key];
         const currentPath = path ? `${path}.${key}` : key;
         // Check if value is undefined - this is the error case
         if (value === undefined) {

package/lib/client/constants.d.ts

@@ -11,6 +11,7 @@
 export declare const ItemTypes: {
     readonly NOTEBOOK: "notebook";
     readonly LEXICAL: "document";
+    readonly DECK: "deck";
     readonly EXERCISE: "exercise";
     readonly CELL: "cell";
     readonly SPACE: "space";

package/lib/client/constants.js

@@ -15,6 +15,7 @@
 export const ItemTypes = {
     NOTEBOOK: 'notebook',
     LEXICAL: 'document',
+    DECK: 'deck',
     EXERCISE: 'exercise',
     CELL: 'cell',
     SPACE: 'space',