@mdxui/do 2.1.1 → 4.0.0

package/dist/lib/index.d.ts

@@ -0,0 +1,798 @@
+export { A as APIError, D as DEFAULT_REQUEST_TIMEOUT, F as FetchWithTimeoutOptions, N as NetworkError, R as RetryConfig, S as SyncError, V as ValidationError, c as camelToTitle, a as capitalize, b as cn, v as createFetchWithTimeout, d as debounce, f as fetchWithTimeout, e as formatBytes, g as formatDate, h as formatDateTime, i as formatDuration, j as formatNumber, k as formatRelativeTime, l as formatSemanticId, m as generateId, n as groupBy, o as isAPIError, p as isNetworkError, q as isSyncError, r as isValidationError, s as parseSemanticId, u as retryWithBackoff, t as truncate } from '../errors-DratdVIz.js';
+export { P as Pagination, Q as QueryKeys, a as agentsKeys, c as createQueryKeys, r as relationshipsKeys, t as thingsKeys, w as workflowsKeys } from '../query-keys-CZNFikIi.js';
+import * as zod from 'zod';
+import { T as Thing, S as SemanticType } from '../thing-BF25aUtJ.js';
+export { $ as $CapnwebContext, c as createCapnwebClient } from '../capnweb-client-Bq78FtEA.js';
+import 'clsx';
+import '../schemas/index.js';
+import '../agents-2_r9e9i7.js';
+
+/**
+ * URL utilities for @mdxui/do
+ *
+ * Provides functions to normalize and derive URLs from the configuration.
+ * These utilities ensure consistent URL formatting across the package.
+ *
+ * @module
+ */
+/**
+ * Normalize a URL to an RPC endpoint
+ *
+ * Transforms various URL formats into a consistent RPC endpoint URL:
+ * - Converts wss:// to https:// and ws:// to http://
+ * - Strips trailing /sync or /rpc if present
+ * - Appends /rpc
+ *
+ * @param url - The base URL (e.g., 'https://api.do/admin' or 'wss://api.do/do/workspace')
+ * @returns The normalized RPC URL (e.g., 'https://api.do/admin/rpc')
+ *
+ * @example
+ * ```typescript
+ * deriveRpcUrl('https://api.do/admin')
+ * // => 'https://api.do/admin/rpc'
+ *
+ * deriveRpcUrl('wss://api.do/do/workspace/sync')
+ * // => 'https://api.do/do/workspace/rpc'
+ *
+ * deriveRpcUrl('https://api.do/admin/rpc')
+ * // => 'https://api.do/admin/rpc' (unchanged)
+ * ```
+ */
+declare function deriveRpcUrl(url: string): string;
+
+/**
+ * Configuration for health check behavior
+ */
+interface HealthCheckConfig {
+    /** API endpoint base URL (e.g., 'https://api.do/admin') */
+    apiEndpoint: string;
+    /** Optional auth token for Bearer authentication */
+    authToken?: string;
+    /** Request timeout in milliseconds (defaults to DEFAULT_REQUEST_TIMEOUT) */
+    requestTimeout?: number;
+    /** Number of retry attempts (defaults to 3) */
+    healthCheckRetries?: number;
+}
+/**
+ * Result of the health check hook
+ */
+interface HealthCheckResult {
+    /** Whether the API is reachable */
+    isConnected: boolean;
+    /** Error from the last failed attempt, if any */
+    connectionError?: Error;
+    /** Manually trigger a health check */
+    checkConnection: () => Promise<void>;
+    /** Whether a check is currently in progress */
+    isChecking: boolean;
+}
+/**
+ * Hook to perform health checks against an API endpoint
+ *
+ * Automatically checks connection on mount with retry and exponential backoff.
+ * Can also be manually triggered via the returned `checkConnection` function.
+ *
+ * @param config - Health check configuration
+ * @returns Health check state and manual trigger function
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { isConnected, connectionError, checkConnection } = useHealthCheck({
+ *     apiEndpoint: 'https://api.do/admin',
+ *     authToken: 'my-token',
+ *     healthCheckRetries: 3,
+ *   })
+ *
+ *   if (connectionError) {
+ *     return <div>Connection failed: {connectionError.message}</div>
+ *   }
+ *
+ *   if (!isConnected) {
+ *     return <div>Connecting...</div>
+ *   }
+ *
+ *   return <div>Connected!</div>
+ * }
+ * ```
+ */
+declare function useHealthCheck(config: HealthCheckConfig): HealthCheckResult;
+
+interface MockClientOptions {
+    /** Initial data to populate the store */
+    initialData?: Thing[];
+    /** Simulated network delay in ms (default: 100) */
+    delay?: number;
+    /** Whether to log operations (default: false) */
+    verbose?: boolean;
+}
+interface MockStore {
+    things: Map<string, Thing>;
+    deletedThings: Set<string>;
+}
+/**
+ * Create a mock client that matches the DOClient interface
+ */
+declare function createMockClient(options?: MockClientOptions): {
+    /**
+     * Namespace operations
+     */
+    Namespace: {
+        list(_params?: {
+            includeSystem?: boolean;
+        }): Promise<{
+            id: string;
+            name: string;
+        }[]>;
+    };
+    /**
+     * Schema operations
+     */
+    Schema: {
+        discover(_params?: {
+            ns?: string;
+        }): Promise<{
+            namespaces: string[];
+            types: string[];
+            schemas: string[];
+        }>;
+        get(params: {
+            ns?: string;
+            type: string;
+        }): Promise<{
+            label: string;
+            id: string;
+            name: string;
+            namespace: string;
+            properties: {
+                label: string;
+                name: string;
+                description: string;
+                required: boolean;
+                rangeIncludes: string[];
+                domainIncludes: string[];
+                isArray: boolean;
+                defaultValue?: unknown;
+            }[];
+            parentTypes: string[];
+            subtypes: string[];
+            description?: string | undefined;
+            examples?: zod.objectOutputType<{
+                '@context': zod.ZodOptional<zod.ZodUnion<[zod.ZodString, zod.ZodRecord<zod.ZodString, zod.ZodUnknown>]>>;
+                '@type': zod.ZodOptional<zod.ZodString>;
+                '@id': zod.ZodOptional<zod.ZodString>;
+            }, zod.ZodTypeAny, "passthrough">[] | undefined;
+        }>;
+    };
+    /**
+     * Thing operations
+     */
+    Thing: {
+        types(params: {
+            ns?: string;
+            includeSystem?: boolean;
+        }): Promise<{
+            name: string;
+            ns: string;
+        }[]>;
+        list(params: {
+            ns?: string;
+            type?: string;
+            limit?: number;
+            offset?: number;
+        }): Promise<{
+            data: {
+                data: {
+                    '@context'?: string | Record<string, unknown> | undefined;
+                    '@type'?: string | undefined;
+                    '@id'?: string | undefined;
+                } & {
+                    [k: string]: unknown;
+                };
+                id: string;
+                type: string;
+                name: string;
+                ns: string;
+                ts: Date;
+                createdAt: Date;
+                updatedAt: Date;
+                variant?: string | undefined;
+                createdBy?: string | undefined;
+                updatedBy?: string | undefined;
+                deletedAt?: Date | null | undefined;
+            }[];
+            total: number;
+        }>;
+        get(params: {
+            ns?: string;
+            type: string;
+            id: string;
+        }): Promise<{
+            data: {
+                '@context'?: string | Record<string, unknown> | undefined;
+                '@type'?: string | undefined;
+                '@id'?: string | undefined;
+            } & {
+                [k: string]: unknown;
+            };
+            id: string;
+            type: string;
+            name: string;
+            ns: string;
+            ts: Date;
+            createdAt: Date;
+            updatedAt: Date;
+            variant?: string | undefined;
+            createdBy?: string | undefined;
+            updatedBy?: string | undefined;
+            deletedAt?: Date | null | undefined;
+        } | null>;
+        create(params: {
+            ns?: string;
+            type: string;
+            name?: string;
+            data: unknown;
+        }): Promise<{
+            data: {
+                '@context'?: string | Record<string, unknown> | undefined;
+                '@type'?: string | undefined;
+                '@id'?: string | undefined;
+            } & {
+                [k: string]: unknown;
+            };
+            id: string;
+            type: string;
+            name: string;
+            ns: string;
+            ts: Date;
+            createdAt: Date;
+            updatedAt: Date;
+            variant?: string | undefined;
+            createdBy?: string | undefined;
+            updatedBy?: string | undefined;
+            deletedAt?: Date | null | undefined;
+        }>;
+        update(params: {
+            ns?: string;
+            type: string;
+            id: string;
+            data: unknown;
+        }): Promise<{
+            data: {
+                '@context'?: string | Record<string, unknown> | undefined;
+                '@type'?: string | undefined;
+                '@id'?: string | undefined;
+            } & {
+                [k: string]: unknown;
+            };
+            id: string;
+            type: string;
+            name: string;
+            ns: string;
+            ts: Date;
+            createdAt: Date;
+            updatedAt: Date;
+            variant?: string | undefined;
+            createdBy?: string | undefined;
+            updatedBy?: string | undefined;
+            deletedAt?: Date | null | undefined;
+        }>;
+        delete(params: {
+            ns?: string;
+            type: string;
+            id: string;
+            hard?: boolean;
+        }): Promise<{
+            success: boolean;
+        }>;
+        versions(_params: {
+            ns?: string;
+            type: string;
+            id: string;
+        }): Promise<never[]>;
+        stats(_params: {
+            ns?: string;
+            type?: string;
+        }): Promise<{
+            total: number;
+            byType: Record<string, number>;
+        }>;
+    };
+    /**
+     * SQL operations (mock implementation)
+     */
+    SQL: {
+        execute(params: {
+            query: string;
+            params?: unknown[];
+        }): Promise<{
+            rows: {
+                id: string;
+                ns: string;
+                type: string;
+                name: string;
+                createdAt: Date;
+                updatedAt: Date;
+                data: string;
+            }[];
+            columns: {
+                name: string;
+                type: string;
+            }[];
+            rowsAffected: number;
+            executionTimeMs: number;
+        }>;
+    };
+    dup: () => /*elided*/ any;
+    onRpcBroken: (_callback: (error: unknown) => void) => void;
+    [Symbol.dispose]: () => void;
+    _store: MockStore;
+    _reset: () => void;
+};
+/**
+ * Create a mock client context - factory function matching DOClient interface
+ */
+declare function $MockContext(options?: MockClientOptions): {
+    /**
+     * Namespace operations
+     */
+    Namespace: {
+        list(_params?: {
+            includeSystem?: boolean;
+        }): Promise<{
+            id: string;
+            name: string;
+        }[]>;
+    };
+    /**
+     * Schema operations
+     */
+    Schema: {
+        discover(_params?: {
+            ns?: string;
+        }): Promise<{
+            namespaces: string[];
+            types: string[];
+            schemas: string[];
+        }>;
+        get(params: {
+            ns?: string;
+            type: string;
+        }): Promise<{
+            label: string;
+            id: string;
+            name: string;
+            namespace: string;
+            properties: {
+                label: string;
+                name: string;
+                description: string;
+                required: boolean;
+                rangeIncludes: string[];
+                domainIncludes: string[];
+                isArray: boolean;
+                defaultValue?: unknown;
+            }[];
+            parentTypes: string[];
+            subtypes: string[];
+            description?: string | undefined;
+            examples?: zod.objectOutputType<{
+                '@context': zod.ZodOptional<zod.ZodUnion<[zod.ZodString, zod.ZodRecord<zod.ZodString, zod.ZodUnknown>]>>;
+                '@type': zod.ZodOptional<zod.ZodString>;
+                '@id': zod.ZodOptional<zod.ZodString>;
+            }, zod.ZodTypeAny, "passthrough">[] | undefined;
+        }>;
+    };
+    /**
+     * Thing operations
+     */
+    Thing: {
+        types(params: {
+            ns?: string;
+            includeSystem?: boolean;
+        }): Promise<{
+            name: string;
+            ns: string;
+        }[]>;
+        list(params: {
+            ns?: string;
+            type?: string;
+            limit?: number;
+            offset?: number;
+        }): Promise<{
+            data: {
+                data: {
+                    '@context'?: string | Record<string, unknown> | undefined;
+                    '@type'?: string | undefined;
+                    '@id'?: string | undefined;
+                } & {
+                    [k: string]: unknown;
+                };
+                id: string;
+                type: string;
+                name: string;
+                ns: string;
+                ts: Date;
+                createdAt: Date;
+                updatedAt: Date;
+                variant?: string | undefined;
+                createdBy?: string | undefined;
+                updatedBy?: string | undefined;
+                deletedAt?: Date | null | undefined;
+            }[];
+            total: number;
+        }>;
+        get(params: {
+            ns?: string;
+            type: string;
+            id: string;
+        }): Promise<{
+            data: {
+                '@context'?: string | Record<string, unknown> | undefined;
+                '@type'?: string | undefined;
+                '@id'?: string | undefined;
+            } & {
+                [k: string]: unknown;
+            };
+            id: string;
+            type: string;
+            name: string;
+            ns: string;
+            ts: Date;
+            createdAt: Date;
+            updatedAt: Date;
+            variant?: string | undefined;
+            createdBy?: string | undefined;
+            updatedBy?: string | undefined;
+            deletedAt?: Date | null | undefined;
+        } | null>;
+        create(params: {
+            ns?: string;
+            type: string;
+            name?: string;
+            data: unknown;
+        }): Promise<{
+            data: {
+                '@context'?: string | Record<string, unknown> | undefined;
+                '@type'?: string | undefined;
+                '@id'?: string | undefined;
+            } & {
+                [k: string]: unknown;
+            };
+            id: string;
+            type: string;
+            name: string;
+            ns: string;
+            ts: Date;
+            createdAt: Date;
+            updatedAt: Date;
+            variant?: string | undefined;
+            createdBy?: string | undefined;
+            updatedBy?: string | undefined;
+            deletedAt?: Date | null | undefined;
+        }>;
+        update(params: {
+            ns?: string;
+            type: string;
+            id: string;
+            data: unknown;
+        }): Promise<{
+            data: {
+                '@context'?: string | Record<string, unknown> | undefined;
+                '@type'?: string | undefined;
+                '@id'?: string | undefined;
+            } & {
+                [k: string]: unknown;
+            };
+            id: string;
+            type: string;
+            name: string;
+            ns: string;
+            ts: Date;
+            createdAt: Date;
+            updatedAt: Date;
+            variant?: string | undefined;
+            createdBy?: string | undefined;
+            updatedBy?: string | undefined;
+            deletedAt?: Date | null | undefined;
+        }>;
+        delete(params: {
+            ns?: string;
+            type: string;
+            id: string;
+            hard?: boolean;
+        }): Promise<{
+            success: boolean;
+        }>;
+        versions(_params: {
+            ns?: string;
+            type: string;
+            id: string;
+        }): Promise<never[]>;
+        stats(_params: {
+            ns?: string;
+            type?: string;
+        }): Promise<{
+            total: number;
+            byType: Record<string, number>;
+        }>;
+    };
+    /**
+     * SQL operations (mock implementation)
+     */
+    SQL: {
+        execute(params: {
+            query: string;
+            params?: unknown[];
+        }): Promise<{
+            rows: {
+                id: string;
+                ns: string;
+                type: string;
+                name: string;
+                createdAt: Date;
+                updatedAt: Date;
+                data: string;
+            }[];
+            columns: {
+                name: string;
+                type: string;
+            }[];
+            rowsAffected: number;
+            executionTimeMs: number;
+        }>;
+    };
+    dup: () => /*elided*/ any;
+    onRpcBroken: (_callback: (error: unknown) => void) => void;
+    [Symbol.dispose]: () => void;
+    _store: MockStore;
+    _reset: () => void;
+};
+
+/**
+ * JSON-RPC Client for DO Admin API
+ *
+ * This client wraps the JSON-RPC API exposed by DO admin servers,
+ * translating the standard Thing/Schema interface to the server's
+ * actual RPC methods.
+ *
+ * Auto-discovers available types and endpoints from the server.
+ *
+ * @module
+ */
+/** SQL execution result */
+interface SQLResult {
+    rows: Record<string, unknown>[];
+    columns: {
+        name: string;
+        type: string;
+    }[];
+    rowsAffected?: number;
+    executionTimeMs?: number;
+}
+interface JsonRpcClientOptions {
+    /** Auth token to include in Authorization header */
+    authToken?: string;
+}
+/**
+ * Create a JSON-RPC compatible client that matches the DOClient interface
+ */
+declare function createJsonRpcClient(baseUrl: string, options?: JsonRpcClientOptions): {
+    /**
+     * Namespace operations
+     */
+    Namespace: {
+        list(_params?: {
+            includeSystem?: boolean;
+        }): Promise<{
+            id: string;
+            name: string;
+        }[]>;
+    };
+    /**
+     * Schema operations
+     */
+    Schema: {
+        discover(_params?: {
+            ns?: string;
+        }): Promise<{
+            namespaces: string[];
+            types: string[];
+            schemas: string[];
+        }>;
+        get(params: {
+            ns?: string;
+            type: string;
+        }): Promise<unknown>;
+    };
+    /**
+     * Thing operations (maps to REST endpoints)
+     */
+    Thing: {
+        types(params: {
+            ns?: string;
+            includeSystem?: boolean;
+        }): Promise<{
+            name: string;
+            ns: string;
+        }[]>;
+        list(params: {
+            ns?: string;
+            type?: string;
+            limit?: number;
+            offset?: number;
+        }): Promise<{
+            data: unknown[];
+            total: number;
+        }>;
+        get(params: {
+            ns?: string;
+            type: string;
+            id: string;
+        }): Promise<unknown>;
+        create(params: {
+            ns?: string;
+            type: string;
+            data: unknown;
+        }): Promise<unknown>;
+        update(params: {
+            ns?: string;
+            type: string;
+            id: string;
+            data: unknown;
+        }): Promise<unknown>;
+        delete(params: {
+            ns?: string;
+            type: string;
+            id: string;
+            hard?: boolean;
+        }): Promise<{
+            success: boolean;
+        }>;
+        versions(_params: {
+            ns?: string;
+            type: string;
+            id: string;
+        }): Promise<never[]>;
+        stats(_params: {
+            ns?: string;
+            type?: string;
+        }): Promise<{
+            total: number;
+            byType: Record<string, number>;
+        }>;
+    };
+    /**
+     * SQL operations
+     */
+    SQL: {
+        execute(params: {
+            query: string;
+            params?: unknown[];
+        }): Promise<SQLResult>;
+    };
+    dup: () => /*elided*/ any;
+    onRpcBroken: (_callback: (error: unknown) => void) => void;
+    [Symbol.dispose]: () => void;
+};
+/**
+ * Create a client context - factory function matching $Context interface
+ */
+declare function $JsonRpcContext(url: string, options?: JsonRpcClientOptions): {
+    /**
+     * Namespace operations
+     */
+    Namespace: {
+        list(_params?: {
+            includeSystem?: boolean;
+        }): Promise<{
+            id: string;
+            name: string;
+        }[]>;
+    };
+    /**
+     * Schema operations
+     */
+    Schema: {
+        discover(_params?: {
+            ns?: string;
+        }): Promise<{
+            namespaces: string[];
+            types: string[];
+            schemas: string[];
+        }>;
+        get(params: {
+            ns?: string;
+            type: string;
+        }): Promise<unknown>;
+    };
+    /**
+     * Thing operations (maps to REST endpoints)
+     */
+    Thing: {
+        types(params: {
+            ns?: string;
+            includeSystem?: boolean;
+        }): Promise<{
+            name: string;
+            ns: string;
+        }[]>;
+        list(params: {
+            ns?: string;
+            type?: string;
+            limit?: number;
+            offset?: number;
+        }): Promise<{
+            data: unknown[];
+            total: number;
+        }>;
+        get(params: {
+            ns?: string;
+            type: string;
+            id: string;
+        }): Promise<unknown>;
+        create(params: {
+            ns?: string;
+            type: string;
+            data: unknown;
+        }): Promise<unknown>;
+        update(params: {
+            ns?: string;
+            type: string;
+            id: string;
+            data: unknown;
+        }): Promise<unknown>;
+        delete(params: {
+            ns?: string;
+            type: string;
+            id: string;
+            hard?: boolean;
+        }): Promise<{
+            success: boolean;
+        }>;
+        versions(_params: {
+            ns?: string;
+            type: string;
+            id: string;
+        }): Promise<never[]>;
+        stats(_params: {
+            ns?: string;
+            type?: string;
+        }): Promise<{
+            total: number;
+            byType: Record<string, number>;
+        }>;
+    };
+    /**
+     * SQL operations
+     */
+    SQL: {
+        execute(params: {
+            query: string;
+            params?: unknown[];
+        }): Promise<SQLResult>;
+    };
+    dup: () => /*elided*/ any;
+    onRpcBroken: (_callback: (error: unknown) => void) => void;
+    [Symbol.dispose]: () => void;
+};
+
+/**
+ * Mock Data Generators for DO Admin
+ *
+ * Generates realistic mock data for Things, Schemas, and other entities.
+ * Used by the mock client for demo/development mode.
+ *
+ * @module
+ */
+
+declare const MOCK_TYPES: string[];
+declare function generateMockSchema(typeName: string): SemanticType;
+declare function generateMockThing(type: string, id?: string): Thing;
+declare function generateMockThings(type: string, count: number): Thing[];
+/**
+ * Generate initial mock data set with various types
+ */
+declare function generateInitialMockData(): Thing[];
+
+export { $JsonRpcContext, $MockContext, type HealthCheckConfig, type HealthCheckResult, MOCK_TYPES, createJsonRpcClient, createMockClient, deriveRpcUrl, generateInitialMockData, generateMockSchema, generateMockThing, generateMockThings, useHealthCheck };