Update examples and TypeScript SDKs

Switch the chat-with-ai example to a package-driven workflow and add Windows usage notes; remove legacy ensure-sdk scripts from examples. Bump local TypeScript SDK versions to 0.5.0-beta.1 and update client/README/quickstart docs and related code (client/types). Update examples (App.tsx and react-ai-chat metadata) and bump dev/runtime dependencies (React, TypeScript, Vite, Playwright, etc.). package-lock.json regenerated to reflect these dependency and SDK changes.

Author: jamals86

AGENTS.md

@@ -68,8 +68,8 @@ use kalamdb_commons::models::UserId;
 - WASM for browser-based client library
 
 **Job Management System** (Phase 9 + Phase 8.5 Complete):
-- **UnifiedJobManager**: Typed JobIds (FL/CL/RT/SE/UC/CO/BK/RS), idempotency, retry logic (3× default with exponential backoff)
-- **8 Job Executors**: FlushExecutor (complete), CleanupExecutor (✅), RetentionExecutor (✅), StreamEvictionExecutor (✅), UserCleanupExecutor (✅), CompactExecutor (placeholder), BackupExecutor (placeholder), RestoreExecutor (placeholder)
+- **UnifiedJobManager**: Typed JobIds across active and legacy-compatible job types, with idempotency and retry logic (3× default with exponential backoff)
+- **Registered Job Executors**: FlushExecutor, CleanupExecutor, StreamEvictionExecutor, CompactExecutor, BackupExecutor, RestoreExecutor, VectorIndexExecutor, TopicRetentionExecutor, and UserExportExecutor. Legacy RT/UC/TC job types remain only for historical `system.jobs` decoding.
 - **Status Transitions**: New → Queued → Running → Completed/Failed/Retrying/Cancelled
 - **Crash Recovery**: Marks Running jobs as Failed on server restart
 - **Idempotency Keys**: Format "{job_type}:{namespace}:{table}:{date}" prevents duplicate jobs

Cargo.lock

@@ -170,7 +170,8 @@ fn build_sql_error_response(
 
 fn build_kalamdb_error_response(err: &KalamDbError, took: f64, is_admin: bool) -> HttpResponse {
     let (status, code, preserve_message) = classify_sql_error(err);
-    build_sql_error_response(status, code, &err.to_string(), None, took, is_admin, preserve_message)
+    let message = err.user_message();
+    build_sql_error_response(status, code, message.as_ref(), None, took, is_admin, preserve_message)
 }
 
 fn build_statement_error_response(
@@ -182,10 +183,11 @@ fn build_statement_error_response(
 ) -> HttpResponse {
     if let Some(kalamdb_err) = err.downcast_ref::<KalamDbError>() {
         let (status, code, preserve_message) = classify_sql_error(kalamdb_err);
+        let message = kalamdb_err.statement_failure_message(statement_index);
         return build_sql_error_response(
             status,
             code,
-            &format!("Statement {} failed: {}", statement_index, kalamdb_err),
+            &message,
             Some(sql),
             took,
             is_admin,
@@ -195,21 +197,23 @@ fn build_statement_error_response(
 
     let err_msg = err.to_string();
     if is_leader_routing_error_message(&err_msg.to_lowercase()) {
+        let message = format!("Statement {statement_index} failed: {err_msg}");
         return build_sql_error_response(
             StatusCode::SERVICE_UNAVAILABLE,
             ErrorCode::NotLeader,
-            &format!("Statement {} failed: {}", statement_index, err_msg),
+            &message,
             Some(sql),
             took,
             is_admin,
             true,
         );
     }
 
+    let message = format!("Statement {statement_index} failed: {err_msg}");
     build_sql_error_response(
         StatusCode::BAD_REQUEST,
         ErrorCode::SqlExecutionError,
-        &format!("Statement {} failed: {}", statement_index, err),
+        &message,
         Some(sql),
         took,
         is_admin,
@@ -370,9 +374,10 @@ pub(super) async fn execute_file_upload_path(
             ));
         },
         Err(err) => {
+            let message = err.to_string();
             return HttpResponse::BadRequest().json(SqlResponse::error_for_privilege(
                 ErrorCode::InvalidSql,
-                &format!("Failed to parse SQL statement after FILE() substitution: {}", err),
+                &message,
                 took_ms(start_time),
                 exec_ctx.is_admin(),
             ));

backend/crates/kalamdb-api/src/http/sql/execution_paths.rs

@@ -2,7 +2,7 @@
 
 use std::sync::Arc;
 
-use kalamdb_commons::{models::UserId, Role};
+use kalamdb_commons::{models::UserId, Role, SqlSubscriptionRow};
 use kalamdb_core::sql::{
     context::ExecutionContext,
     executor::{PreparedExecutionStatement, ScalarValue, SqlExecutor},
@@ -60,18 +60,12 @@ pub fn execution_result_to_query_result(
             subscription_id,
             channel,
             select_query,
-        } => {
-            let sub_data = serde_json::json!({
-                "status": "active",
-                "ws_url": channel,
-                "subscription": {
-                    "id": subscription_id,
-                    "sql": select_query
-                },
-                "message": "WebSocket subscription created. Connect to ws_url to receive updates."
-            });
-            Ok(QueryResult::subscription(sub_data))
-        },
+        } => Ok(QueryResult::subscription(SqlSubscriptionRow::new(
+            subscription_id,
+            channel,
+            select_query,
+            "Subscription created. Connect to ws_url to receive updates.",
+        ))),
         ExecutionResult::JobKilled { job_id, status } => {
             Ok(QueryResult::with_message(format!("Job {} killed: {}", job_id, status)))
         },

backend/crates/kalamdb-api/src/http/sql/helpers/executor.rs

@@ -7,7 +7,7 @@ use std::fmt;
 use kalamdb_commons::{
     models::{datatypes::KalamDataType, KalamCellValue},
     schemas::SchemaField,
-    ResponseStatus,
+    ResponseStatus, SqlSubscriptionRow,
 };
 use serde::{Deserialize, Serialize, Serializer};
 
@@ -106,11 +106,17 @@ impl ErrorCode {
     #[inline]
     fn public_message(&self) -> Option<&'static str> {
         match self {
-            ErrorCode::BatchParseError => Some("Failed to parse SQL batch"),
-            ErrorCode::SqlExecutionError => Some("SQL statement failed"),
-            ErrorCode::InvalidSql => Some("SQL statement is invalid or not allowed"),
+            ErrorCode::BatchParseError => {
+                Some("Failed to parse SQL batch. Review the SQL and try again.")
+            },
+            ErrorCode::SqlExecutionError => {
+                Some("SQL statement failed. Review the statement and try again.")
+            },
+            ErrorCode::InvalidSql => {
+                Some("SQL statement is invalid or not allowed. Review the SQL and try again.")
+            },
             ErrorCode::TableNotFound => Some("Requested table is not available"),
-            ErrorCode::InternalError => Some("SQL request failed"),
+            ErrorCode::InternalError => Some("SQL request failed. Retry the request."),
             _ => None,
         }
     }
@@ -357,29 +363,23 @@ impl QueryResult {
     /// Create a result for a SUBSCRIBE TO statement
     ///
     /// Returns subscription metadata as a single row result
-    pub fn subscription(subscription_data: serde_json::Value) -> Self {
+    pub fn subscription(subscription_data: SqlSubscriptionRow) -> Self {
         let schema = vec![
             SchemaField::new("status", KalamDataType::Text, 0),
             SchemaField::new("ws_url", KalamDataType::Text, 1),
             SchemaField::new("subscription", KalamDataType::Json, 2),
             SchemaField::new("message", KalamDataType::Text, 3),
         ];
 
-        // Extract values in schema order
-        let row = if let serde_json::Value::Object(map) = subscription_data {
-            vec![
-                KalamCellValue::from(map.get("status").cloned().unwrap_or(serde_json::Value::Null)),
-                KalamCellValue::from(map.get("ws_url").cloned().unwrap_or(serde_json::Value::Null)),
-                KalamCellValue::from(
-                    map.get("subscription").cloned().unwrap_or(serde_json::Value::Null),
-                ),
-                KalamCellValue::from(
-                    map.get("message").cloned().unwrap_or(serde_json::Value::Null),
-                ),
-            ]
-        } else {
-            vec![KalamCellValue::null(); 4]
-        };
+        let row = vec![
+            KalamCellValue::text(subscription_data.status.as_str()),
+            KalamCellValue::text(subscription_data.ws_url),
+            KalamCellValue::from(
+                serde_json::to_value(subscription_data.subscription)
+                    .expect("SQL subscription descriptor should serialize"),
+            ),
+            KalamCellValue::text(subscription_data.message),
+        ];
 
         Self {
             schema,
@@ -444,6 +444,30 @@ mod tests {
         assert!(json.contains("\"data_type\":\"Timestamp\""));
     }
 
+    #[test]
+    fn test_subscription_result_uses_shared_row_type() {
+        let result = QueryResult::subscription(SqlSubscriptionRow::new(
+            "sub-1",
+            "ws://localhost:8080/v1/ws",
+            "SELECT * FROM chat.messages",
+            "Subscription created. Connect to ws_url to receive updates.",
+        ));
+
+        let rows = result.rows.as_ref().expect("subscription result should include a row");
+        assert_eq!(rows[0][0].as_str(), Some("subscription_required"));
+        assert_eq!(rows[0][1].as_str(), Some("ws://localhost:8080/v1/ws"));
+        assert_eq!(rows[0][3].as_str(), Some("Subscription created. Connect to ws_url to receive updates."));
+
+        let subscription = rows[0][2]
+            .as_object()
+            .expect("subscription column should be a JSON object");
+        assert_eq!(subscription.get("id").and_then(|value| value.as_str()), Some("sub-1"));
+        assert_eq!(
+            subscription.get("sql").and_then(|value| value.as_str()),
+            Some("SELECT * FROM chat.messages")
+        );
+    }
+
     #[test]
     fn test_column_names() {
         let schema = vec![
@@ -505,7 +529,10 @@ mod tests {
 
         let error = response.error.expect("error response should include an error payload");
         assert_eq!(error.code, ErrorCode::SqlExecutionError);
-        assert_eq!(error.message, "SQL statement failed");
+        assert_eq!(
+            error.message,
+            "SQL statement failed. Review the statement and try again.",
+        );
         assert!(error.details.is_none());
     }
 

backend/crates/kalamdb-api/src/http/sql/models/sql_response.rs

@@ -185,9 +185,10 @@ pub(super) fn split_and_prepare_statements(
     }
 
     let raw_statements = kalamdb_sql::split_statements(sql).map_err(|err| {
+        let message = err.to_string();
         HttpResponse::BadRequest().json(SqlResponse::error_for_privilege(
             ErrorCode::BatchParseError,
-            &format!("Failed to parse SQL batch: {}", err),
+            &message,
             took_ms(start_time),
             exec_ctx.is_admin(),
         ))

backend/crates/kalamdb-api/src/http/sql/statements.rs

@@ -199,7 +199,7 @@ pub async fn handle_subscribe(
                 kalamdb_live::error::LiveError::InvalidOperation(_) => WsErrorCode::Unsupported,
                 _ => WsErrorCode::SubscriptionFailed,
             };
-            let message = e.to_string();
+            let message = e.user_message();
             // Use warn for "expected" client errors (table gone, bad SQL) to avoid
             // flooding logs during benchmark teardown; keep error for server-side issues.
             match &code {
@@ -216,8 +216,14 @@ pub async fn handle_subscribe(
                     );
                 },
             }
-            let _ =
-                send_error(session, &subscription_id, code, &message, compression_enabled).await;
+            let _ = send_error(
+                session,
+                &subscription_id,
+                code,
+                message.as_ref(),
+                compression_enabled,
+            )
+            .await;
             Ok(())
         },
     }

backend/crates/kalamdb-api/src/ws/events/subscription.rs

@@ -1,5 +1,7 @@
 use serde::{Deserialize, Serialize};
 
+use crate::websocket_messages::SubscriptionOptions;
+
 /// Health check response from the server.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct HealthCheckResponse {
@@ -71,3 +73,70 @@ impl std::fmt::Display for ResponseStatus {
         }
     }
 }
+
+/// Status values returned by `SUBSCRIBE TO` over the SQL HTTP API.
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "snake_case")]
+pub enum SqlSubscriptionStatus {
+    SubscriptionRequired,
+    Active,
+}
+
+impl SqlSubscriptionStatus {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            SqlSubscriptionStatus::SubscriptionRequired => "subscription_required",
+            SqlSubscriptionStatus::Active => "active",
+        }
+    }
+}
+
+impl std::fmt::Display for SqlSubscriptionStatus {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "{}", self.as_str())
+    }
+}
+
+/// Nested subscription metadata returned by `SUBSCRIBE TO` over SQL HTTP.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+pub struct SqlSubscriptionDescriptor {
+    pub id: String,
+    pub sql: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub options: Option<SubscriptionOptions>,
+}
+
+impl SqlSubscriptionDescriptor {
+    pub fn new(id: impl Into<String>, sql: impl Into<String>) -> Self {
+        Self {
+            id: id.into(),
+            sql: sql.into(),
+            options: None,
+        }
+    }
+}
+
+/// Single-row payload returned for `SUBSCRIBE TO` via `/v1/api/sql`.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+pub struct SqlSubscriptionRow {
+    pub status: SqlSubscriptionStatus,
+    pub ws_url: String,
+    pub subscription: SqlSubscriptionDescriptor,
+    pub message: String,
+}
+
+impl SqlSubscriptionRow {
+    pub fn new(
+        subscription_id: impl Into<String>,
+        ws_url: impl Into<String>,
+        sql: impl Into<String>,
+        message: impl Into<String>,
+    ) -> Self {
+        Self {
+            status: SqlSubscriptionStatus::SubscriptionRequired,
+            ws_url: ws_url.into(),
+            subscription: SqlSubscriptionDescriptor::new(subscription_id, sql),
+            message: message.into(),
+        }
+    }
+}

backend/crates/kalamdb-commons/src/api_models.rs

@@ -72,6 +72,7 @@ extern crate self as kalamdb_commons;
 // Re-export commonly used types at crate root
 pub use api_models::{
     ClusterHealthResponse, ClusterNodeHealth, HealthCheckResponse, ResponseStatus,
+    SqlSubscriptionDescriptor, SqlSubscriptionRow, SqlSubscriptionStatus,
 };
 pub use constants::{MAX_SQL_QUERY_LENGTH, RESERVED_NAMESPACE_NAMES};
 #[cfg(feature = "conversions")]

backend/crates/kalamdb-commons/src/lib.rs

@@ -194,8 +194,7 @@ impl CoreClusterHandler {
                 rows: None,
                 row_count: 1,
                 message: Some(format!(
-                    "Subscription {} on channel {} for query: {}",
-                    subscription_id, channel, select_query
+                    "Subscription {subscription_id} created. Connect to {channel} to receive updates for query: {select_query}"
                 )),
                 as_user: as_user.to_string(),
             }),
@@ -350,10 +349,11 @@ impl ClusterMessageHandler for CoreClusterHandler {
                 ));
             },
             Err(e) => {
+                let message = e.to_string();
                 return Ok(Self::error_payload(
                     400,
                     "BATCH_PARSE_ERROR",
-                    &format!("Failed to parse SQL batch: {}", e),
+                    &message,
                     started_at,
                 ));
             },
@@ -409,7 +409,7 @@ impl ClusterMessageHandler for CoreClusterHandler {
                         return Ok(Self::error_payload(
                             400,
                             "SQL_EXECUTION_ERROR",
-                            &format!("Statement {} failed: {}", idx + 1, e),
+                            &e.statement_failure_message(idx + 1),
                             started_at,
                         ));
                     },
@@ -461,7 +461,7 @@ impl ClusterMessageHandler for CoreClusterHandler {
                     return Ok(Self::error_payload(
                         400,
                         "SQL_EXECUTION_ERROR",
-                        &format!("Statement {} failed: {}", idx + 1, e),
+                        &e.statement_failure_message(idx + 1),
                         started_at,
                     ));
                 },