@mdxui/do 2.1.1 → 3.0.0

package/dist/components/index.js

@@ -1,8 +1,4 @@
-export { AgentExecutePanel, AgentFeedbackPanel, AgentHistoryTable, AgentsGrid, ConfirmDialog, DOErrorBoundary, DOHeader, DOShell, DOSidebar, DOSidebarHeader, StatsCards, SyncStatusIndicator, ThingForm, ThingFormDialog, ThingsList, ThingsPage, ToastContainer, ToastProvider, TriggerWorkflowDialog, WorkflowExecutionView, WorkflowsList, defaultNavItems, defaultStats, useErrorBoundary, useShell, useToast } from '../chunk-NXPXL5NA.js';
-import '../chunk-EEDMN7UF.js';
-import '../chunk-GKSP5RIA.js';
-import '../chunk-GGO5GW72.js';
-import '../chunk-XF6LKY2M.js';
-import '../chunk-G3PMV62Z.js';
+export { DOErrorBoundary, useErrorBoundary } from '../chunk-EQVOEEQO.js';
+import '../chunk-Y52IEYVM.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/config-CmZBQQaT.d.ts

@@ -0,0 +1,122 @@
+import { ReactNode } from 'react';
+import { i as DOAdminConfig } from './do-C-t9UgjT.js';
+
+/**
+ * Configuration types for DOShell
+ *
+ * These types define the configuration options for the DO Admin Dashboard Shell,
+ * including authentication, branding, and routing configuration.
+ */
+
+/**
+ * Identity configuration for WorkOS AuthKit integration
+ */
+interface DOIdentity {
+    /** WorkOS AuthKit client ID */
+    clientId: string;
+    /** Custom API hostname for WorkOS (optional) */
+    apiHostname?: string;
+    /**
+     * Enable development mode for testing without real auth.
+     * When true, WorkOS AuthKit will use its built-in dev mode.
+     */
+    devMode?: boolean;
+    /** OAuth redirect URI (defaults to current origin + basePath) */
+    redirectUri?: string;
+    /**
+     * Whether authentication is required.
+     * @default true
+     */
+    required?: boolean;
+    /**
+     * Action when user is not authenticated.
+     * - 'redirect': Redirect to unauthenticatedRedirectUrl
+     * - 'landing': Show landing page (custom or default)
+     * - 'allow': Allow access without auth (useful for public routes)
+     * @default 'landing'
+     */
+    onUnauthenticated?: 'redirect' | 'landing' | 'allow';
+    /** URL to redirect to when unauthenticated and onUnauthenticated is 'redirect' */
+    unauthenticatedRedirectUrl?: string;
+    /** Custom landing component to show when not authenticated */
+    landingComponent?: ReactNode;
+}
+/**
+ * Branding configuration for the shell
+ */
+interface DOBranding {
+    /** Application name shown in sidebar header */
+    name?: string;
+    /** Logo element or image */
+    logo?: ReactNode;
+    /** Favicon URL */
+    favicon?: string;
+}
+/**
+ * Theme configuration
+ */
+interface DOTheme {
+    /** Theme mode */
+    mode?: 'light' | 'dark' | 'system';
+}
+/**
+ * Custom route definition for extending the shell
+ */
+interface DOCustomRoute {
+    /** Route path (e.g., '/custom-page') */
+    path: string;
+    /** Navigation title */
+    title: string;
+    /** Navigation icon (Lucide icon component) */
+    icon?: React.ComponentType<{
+        className?: string;
+    }>;
+    /** Component to render for this route */
+    component: React.ComponentType;
+    /** Parent group in navigation (optional) */
+    group?: 'main' | 'development' | 'dataModel' | 'saas' | 'admin' | 'custom';
+}
+/**
+ * Main configuration for DOShell
+ */
+interface DOShellConfig {
+    /** RPC and API configuration (existing DOAdminConfig) */
+    do: DOAdminConfig;
+    /** Base URL path for the shell (e.g., '/admin') */
+    basePath?: string;
+    /** Default namespace to select on load */
+    defaultNamespace?: string;
+    /** Branding configuration */
+    branding?: DOBranding;
+    /** Theme configuration */
+    theme?: DOTheme;
+    /**
+     * Enable/disable built-in routes.
+     * Use route names as keys (e.g., { agents: false, workflows: false })
+     */
+    routes?: Partial<Record<string, boolean>>;
+    /** Add custom routes to the shell */
+    customRoutes?: DOCustomRoute[];
+    /** Authentication configuration */
+    identity: DOIdentity;
+    /**
+     * Development token for bypassing auth in dev mode.
+     * Use with identity.devMode for local development.
+     */
+    devToken?: string;
+    /** Enable debug mode with extra logging */
+    debug?: boolean;
+}
+/**
+ * Context value provided by DOShellProvider
+ */
+interface DOShellContextValue {
+    /** Shell configuration */
+    config: DOShellConfig;
+    /** Current namespace */
+    namespace: string;
+    /** Set current namespace */
+    setNamespace: (ns: string) => void;
+}
+
+export type { DOIdentity as D, DOBranding as a, DOTheme as b, DOCustomRoute as c, DOShellConfig as d, DOShellContextValue as e };

package/dist/{do-CaQVueZw.d.ts → do-C-t9UgjT.d.ts}

@@ -11,7 +11,7 @@ import { z } from 'zod';
  * - ctx.storage.put/get/delete for persistence
  * - blockConcurrencyWhile() for atomic operations
  * - alarms for scheduled events
- * - RPC via fetch for inter-DO communication
+ * - RPC via capnweb for communication
  */
 
 /**
@@ -138,51 +138,34 @@ interface DOMetrics {
     alarmsTriggered: number;
 }
 /**
- * Conflict resolution strategy for sync
- */
-type ConflictStrategy = 'last-write-wins' | 'merge' | ConflictResolver;
-type ConflictResolver = <T>(local: T, remote: T, base?: T) => T;
-/**
- * Offline persistence configuration
- */
-interface OfflineConfig {
-    /** Enable IndexedDB persistence */
-    enabled: boolean;
-    /** IndexedDB database name */
-    dbName?: string;
-}
-/**
- * Sync status for DO connection
+ * @deprecated Sync status is no longer available in the simplified RPC-only architecture.
+ * Kept for backward compatibility.
  */
 type SyncStatus = 'disconnected' | 'connecting' | 'syncing' | 'synced' | 'error';
 /**
  * Configuration for DO admin interface
  *
- * Supports two modes:
- * - REST API mode: Traditional fetch-based API calls
- * - TanStack DB mode: Reactive local-first with WebSocket sync
+ * Simplified single-mode RPC architecture using capnweb.
  */
 interface DOAdminConfig {
-    /** API endpoint for DO management (REST mode) */
+    /** API endpoint for DO management and health checks */
     apiEndpoint: string;
-    /** WebSocket URL for Durable Object sync (TanStack DB mode) */
-    doUrl?: string;
+    /**
+     * Explicit RPC URL for capnweb session.
+     * If not provided, defaults to `${apiEndpoint}/rpc`
+     */
+    rpcUrl?: string;
     /** Authentication method */
-    authMethod: 'jwt' | 'api-key' | 'oauth';
+    authMethod: 'none' | 'jwt' | 'api-key' | 'oauth';
     /** Auth token (JWT or API key) */
     authToken?: string;
     /** Available DO bindings */
     bindings: DOBinding[];
-    /** Enable real-time updates */
+    /**
+     * Enable real-time updates via RPC subscriptions.
+     * Note: This requires backend support for RPC subscriptions.
+     */
     realTimeUpdates: boolean;
-    /** WebSocket endpoint for real-time (legacy, prefer doUrl) */
-    wsEndpoint?: string;
-    /** Conflict resolution strategy for sync */
-    conflictStrategy?: ConflictStrategy;
-    /** Offline persistence configuration */
-    offline?: OfflineConfig;
-    /** Collections to auto-sync */
-    collections?: string[];
     /** Number of retries for health check (default: 3) */
     healthCheckRetries?: number;
     /**
@@ -190,6 +173,21 @@ interface DOAdminConfig {
      * @default 30000 (30 seconds)
      */
     requestTimeout?: number;
+    /**
+     * Skip the health check on initial connection.
+     * Useful for backends without a /health endpoint.
+     * @default false
+     */
+    skipHealthCheck?: boolean;
+    /**
+     * Client type for RPC communication.
+     * - 'capnweb-ws': Cap'n Proto over WebSocket - persistent connection, real-time updates (default)
+     * - 'capnweb-http': Cap'n Proto over HTTP batch - stateless requests
+     * - 'capnweb': Legacy @dotdo/client wrapper
+     * - 'json-rpc': JSON-RPC over HTTP - simple JSON format
+     * @default 'capnweb-ws'
+     */
+    clientType?: 'capnweb-ws' | 'capnweb-http' | 'capnweb' | 'json-rpc';
 }
 
-export type { ConflictStrategy as C, DOAdminConfig as D, OfflineConfig as O, SyncStatus as S, DOStatus as a, DOClassType as b, DOInstance as c, DOAlarm as d, DOStorageEntry as e, DOBinding as f, DORPCMethod as g, DOHealthCheck as h, DOMetrics as i, ConflictResolver as j };
+export type { DOStatus as D, SyncStatus as S, DOClassType as a, DOInstance as b, DOAlarm as c, DOStorageEntry as d, DOBinding as e, DORPCMethod as f, DOHealthCheck as g, DOMetrics as h, DOAdminConfig as i };

package/dist/errors-B4Oyyj4Z.d.ts

@@ -0,0 +1,346 @@
+import { ClassValue } from 'clsx';
+
+/**
+ * Merge class names with Tailwind CSS support
+ */
+declare function cn(...inputs: ClassValue[]): string;
+/**
+ * Format a semantic ID (ns/type/id)
+ */
+declare function formatSemanticId(ns: string, type: string, id: string): string;
+/**
+ * Parse a semantic ID into components
+ * Format: type/namespace/id where namespace can contain slashes
+ * @throws Error if the semantic ID format is invalid
+ */
+declare function parseSemanticId(semanticId: string): {
+    type: string;
+    namespace: string;
+    id: string;
+};
+/**
+ * Format a date for display
+ */
+declare function formatDate(date: Date | string, options?: Intl.DateTimeFormatOptions): string;
+/**
+ * Format a date and time for display
+ */
+declare function formatDateTime(date: Date | string, options?: Intl.DateTimeFormatOptions): string;
+/**
+ * Format a relative time (e.g., "2 hours ago")
+ */
+declare function formatRelativeTime(date: Date | string): string;
+/**
+ * Format a number with abbreviation (1K, 1M, etc.)
+ */
+declare function formatNumber(num: number): string;
+/**
+ * Format bytes to human-readable string
+ */
+declare function formatBytes(bytes: number): string;
+/**
+ * Format duration in milliseconds to human-readable string
+ */
+declare function formatDuration(ms: number): string;
+/**
+ * Truncate text with ellipsis
+ */
+declare function truncate(text: string, maxLength: number, suffix?: string): string;
+/**
+ * Capitalize first letter
+ */
+declare function capitalize(text: string): string;
+/**
+ * Convert camelCase to Title Case
+ */
+declare function camelToTitle(text: string): string;
+/**
+ * Generate a random ID
+ */
+declare function generateId(prefix?: string): string;
+/**
+ * Debounce function
+ *
+ * Creates a debounced version of the function that delays execution
+ * until after the specified delay has passed since the last call.
+ *
+ * @example
+ * ```ts
+ * const debouncedSearch = debounce((query: string) => {
+ *   fetch(`/search?q=${query}`)
+ * }, 300)
+ *
+ * // Only the last call within 300ms will execute
+ * debouncedSearch('h')
+ * debouncedSearch('he')
+ * debouncedSearch('hello') // Only this one runs
+ * ```
+ */
+declare function debounce<Args extends unknown[]>(fn: (...args: Args) => unknown, delay: number): (...args: Args) => void;
+/**
+ * Group array by key
+ */
+declare function groupBy<T, K extends string | number>(array: T[], keyFn: (item: T) => K): Record<K, T[]>;
+/**
+ * Configuration for retry with exponential backoff
+ */
+interface RetryConfig {
+    /** Maximum number of retry attempts (default: 3) */
+    maxRetries?: number;
+    /** Base multiplier for backoff in ms (default: 1000). Backoff = 2^attempt * multiplier */
+    backoffMultiplier?: number;
+    /** Optional AbortSignal for cancellation */
+    signal?: AbortSignal;
+    /** Callback invoked before each retry with the error and attempt number */
+    onRetry?: (error: Error, attempt: number) => void;
+}
+/**
+ * Execute an async function with retry and exponential backoff
+ *
+ * Retries the provided function on failure with exponential backoff delays.
+ * Backoff formula: 2^attempt * backoffMultiplier (default: 1s, 2s, 4s, etc.)
+ *
+ * @param fn - Async function to execute
+ * @param config - Retry configuration
+ * @returns Promise resolving to the function result
+ * @throws Last error if all retries exhausted
+ *
+ * @example
+ * ```ts
+ * // Basic usage
+ * const result = await retryWithBackoff(
+ *   () => fetch('/api/health'),
+ *   { maxRetries: 3 }
+ * )
+ *
+ * // With cancellation
+ * const controller = new AbortController()
+ * const result = await retryWithBackoff(
+ *   () => fetch('/api/health'),
+ *   { maxRetries: 3, signal: controller.signal }
+ * )
+ * // Later: controller.abort()
+ *
+ * // With retry callback
+ * const result = await retryWithBackoff(
+ *   () => fetch('/api/health'),
+ *   {
+ *     maxRetries: 3,
+ *     onRetry: (error, attempt) => console.log(`Retry ${attempt}: ${error.message}`)
+ *   }
+ * )
+ * ```
+ */
+declare function retryWithBackoff<T>(fn: () => Promise<T>, config?: RetryConfig): Promise<T>;
+
+/**
+ * Fetch wrapper with configurable timeout
+ *
+ * Prevents indefinite hangs on slow networks or unresponsive servers
+ * by wrapping fetch with AbortController-based timeout.
+ *
+ * @module
+ */
+/**
+ * Default timeout in milliseconds (30 seconds)
+ */
+declare const DEFAULT_REQUEST_TIMEOUT = 30000;
+/**
+ * Extended RequestInit that includes optional timeout
+ */
+interface FetchWithTimeoutOptions extends RequestInit {
+    /** Timeout in milliseconds. Defaults to 30000 (30 seconds) */
+    timeout?: number;
+}
+/**
+ * Fetch wrapper with configurable timeout
+ *
+ * Uses AbortController to cancel requests that exceed the timeout.
+ * If the request already has a signal, a composite abort will be used
+ * that respects both the existing signal and the timeout.
+ *
+ * @param url - The URL to fetch
+ * @param options - Fetch options including optional timeout
+ * @returns Promise resolving to the Response
+ * @throws {DOMException} AbortError if the request times out
+ *
+ * @example
+ * ```typescript
+ * // Basic usage with default 30s timeout
+ * const response = await fetchWithTimeout('https://api.example.com/data')
+ *
+ * // Custom timeout
+ * const response = await fetchWithTimeout('https://api.example.com/data', {
+ *   timeout: 5000, // 5 seconds
+ * })
+ *
+ * // With other fetch options
+ * const response = await fetchWithTimeout('https://api.example.com/data', {
+ *   method: 'POST',
+ *   headers: { 'Content-Type': 'application/json' },
+ *   body: JSON.stringify({ key: 'value' }),
+ *   timeout: 10000,
+ * })
+ * ```
+ */
+declare function fetchWithTimeout(url: string, options?: FetchWithTimeoutOptions): Promise<Response>;
+/**
+ * Create a fetch wrapper with a default timeout from config
+ *
+ * Useful for creating a configured fetch function that can be shared
+ * across multiple hooks/components with consistent timeout behavior.
+ *
+ * @param defaultTimeout - Default timeout in milliseconds
+ * @returns A fetch function with the default timeout applied
+ *
+ * @example
+ * ```typescript
+ * // Create a configured fetch
+ * const configuredFetch = createFetchWithTimeout(5000)
+ *
+ * // Use it (timeout defaults to 5000ms)
+ * const response = await configuredFetch('https://api.example.com/data')
+ *
+ * // Override the default timeout
+ * const response = await configuredFetch('https://api.example.com/data', {
+ *   timeout: 10000,
+ * })
+ * ```
+ */
+declare function createFetchWithTimeout(defaultTimeout: number): (url: string, options?: FetchWithTimeoutOptions) => Promise<Response>;
+
+/**
+ * Standardized error classes for @mdxui/do
+ *
+ * These classes provide consistent error handling across the package:
+ * - APIError: HTTP/RPC errors from the backend
+ * - NetworkError: Connection/fetch failures
+ * - ValidationError: Input validation errors
+ * - SyncError: Real-time sync errors
+ *
+ * @example
+ * ```typescript
+ * import { APIError, NetworkError, isAPIError } from '@mdxui/do'
+ *
+ * try {
+ *   const response = await fetch(url)
+ *   if (!response.ok) {
+ *     throw APIError.fromResponse(response)
+ *   }
+ * } catch (error) {
+ *   if (isAPIError(error)) {
+ *     console.log(`API error ${error.code}: ${error.message}`)
+ *     if (error.status === 401) {
+ *       // Handle auth error
+ *     }
+ *   } else if (isNetworkError(error)) {
+ *     console.log('Network unavailable, will retry...')
+ *   }
+ * }
+ * ```
+ */
+/**
+ * API error from HTTP/RPC calls
+ *
+ * Provides structured error information including:
+ * - code: Machine-readable error code (e.g., 'HTTP_404', 'VALIDATION_ERROR')
+ * - message: Human-readable error message
+ * - status: HTTP status code (when applicable)
+ * - details: Additional error details from the server
+ */
+declare class APIError extends Error {
+    readonly code: string;
+    readonly status?: number | undefined;
+    readonly details?: Record<string, unknown> | undefined;
+    constructor(code: string, message: string, status?: number | undefined, details?: Record<string, unknown> | undefined);
+    /**
+     * Create an APIError from a fetch Response
+     *
+     * @param response - The Response object from fetch
+     * @param body - Optional response body text (if already read)
+     * @returns An APIError with HTTP status information
+     *
+     * @example
+     * ```typescript
+     * const response = await fetch('/api/things')
+     * if (!response.ok) {
+     *   throw APIError.fromResponse(response, await response.text())
+     * }
+     * ```
+     */
+    static fromResponse(response: Response, body?: string): APIError;
+    /**
+     * Type guard to check if an error is an APIError
+     */
+    static isAPIError(error: unknown): error is APIError;
+}
+/**
+ * Network-level error (connection failures, timeouts, etc.)
+ *
+ * Use for errors that occur before an HTTP response is received:
+ * - DNS resolution failures
+ * - Connection refused
+ * - Request timeouts
+ * - CORS errors
+ */
+declare class NetworkError extends Error {
+    readonly cause?: Error | undefined;
+    constructor(message: string, cause?: Error | undefined);
+}
+/**
+ * Validation error with field-level details
+ *
+ * Use when input data fails validation checks.
+ * The fields property maps field names to arrays of error messages.
+ *
+ * @example
+ * ```typescript
+ * throw new ValidationError('Invalid input', {
+ *   email: ['Invalid email format'],
+ *   name: ['Name is required', 'Name must be at least 2 characters'],
+ * })
+ * ```
+ */
+declare class ValidationError extends Error {
+    readonly fields: Record<string, string[]>;
+    constructor(message: string, fields: Record<string, string[]>);
+}
+/**
+ * Real-time sync error
+ *
+ * Use for errors in the sync protocol (WebSocket, EventSource, etc.).
+ * The operation property indicates what sync operation failed.
+ * The recoverable property indicates whether the client should retry.
+ *
+ * @example
+ * ```typescript
+ * // Recoverable connection error - client should retry
+ * throw new SyncError('WebSocket disconnected', 'connect', true)
+ *
+ * // Non-recoverable push error - user intervention needed
+ * throw new SyncError('Conflict: record modified by another user', 'push', false)
+ * ```
+ */
+declare class SyncError extends Error {
+    readonly operation: 'push' | 'pull' | 'connect';
+    readonly recoverable: boolean;
+    constructor(message: string, operation: 'push' | 'pull' | 'connect', recoverable: boolean);
+}
+/**
+ * Type guard to check if an error is an APIError
+ */
+declare function isAPIError(error: unknown): error is APIError;
+/**
+ * Type guard to check if an error is a NetworkError
+ */
+declare function isNetworkError(error: unknown): error is NetworkError;
+/**
+ * Type guard to check if an error is a ValidationError
+ */
+declare function isValidationError(error: unknown): error is ValidationError;
+/**
+ * Type guard to check if an error is a SyncError
+ */
+declare function isSyncError(error: unknown): error is SyncError;
+
+export { APIError as A, DEFAULT_REQUEST_TIMEOUT as D, type FetchWithTimeoutOptions as F, NetworkError as N, type RetryConfig as R, SyncError as S, ValidationError as V, formatDate as a, formatDateTime as b, cn as c, formatRelativeTime as d, formatNumber as e, formatSemanticId as f, formatBytes as g, formatDuration as h, capitalize as i, camelToTitle as j, generateId as k, debounce as l, groupBy as m, fetchWithTimeout as n, isAPIError as o, parseSemanticId as p, isNetworkError as q, isValidationError as r, isSyncError as s, truncate as t, retryWithBackoff as u, createFetchWithTimeout as v };