@mdxui/do 2.1.1 → 4.0.0

package/README.md

@@ -3,48 +3,59 @@
 [![npm version](https://img.shields.io/npm/v/@mdxui/do.svg)](https://www.npmjs.com/package/@mdxui/do)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
-Admin interface for the .do platform - manage Durable Objects, Things, Relationships, Workflows, Agents, and Integrations.
-
-## What is @mdxui/do?
-
-`@mdxui/do` provides a React-based admin interface for the [.do platform](https://do.md). It enables you to manage semantic entities (Things), graph relationships, business process workflows, and autonomous AI agents. Built on TanStack Query, the library supports two operational modes: traditional REST API fetching or local-first reactive data with TanStack DB and WebSocket sync.
+React components and hooks for building admin interfaces for .do Durable Objects.
 
 ## Installation
 
 ```bash
-npm install @mdxui/do
-# or
 pnpm add @mdxui/do
-# or
-yarn add @mdxui/do
 ```
 
-### Peer Dependencies
+## Quick Start
+
+### Full Admin Dashboard
 
-```bash
-npm install react react-dom
+Use `DOApp` for a complete admin experience with routing and authentication:
+
+```tsx
+import { DOApp } from '@mdxui/do/app'
+
+function App() {
+  return (
+    <DOApp
+      config={{
+        do: {
+          apiEndpoint: 'https://api.example.do',
+          authMethod: 'jwt',
+          bindings: [],
+          realTimeUpdates: false,
+        },
+        identity: {
+          clientId: 'client_xxx', // WorkOS client ID
+          devMode: true,
+        },
+      }}
+    />
+  )
+}
 ```
 
-## Quick Start
+### Custom UI with Provider
 
-Wrap your application with `DOProvider` and start using hooks to fetch and mutate data:
+For custom UIs, use `DOProvider` directly:
 
 ```tsx
-import { DOProvider, useThings, useCreateThing } from '@mdxui/do'
+import { DOProvider, useThings } from '@mdxui/do'
 
 function App() {
   return (
     <DOProvider
       config={{
-        apiEndpoint: 'https://api.example.do/admin',
-        doUrl: 'wss://api.example.do/do/workspace',
-        authMethod: 'jwt',
-        authToken: 'your-token',
+        apiEndpoint: 'https://api.example.do',
+        authMethod: 'none',
         bindings: [],
-        realTimeUpdates: true,
-        collections: ['Task', 'User', 'Project'],
+        realTimeUpdates: false,
       }}
-      initialNamespace="default"
     >
       <TaskList />
     </DOProvider>
@@ -52,359 +63,140 @@ function App() {
 }
 
 function TaskList() {
-  const { data, isLoading, error } = useThings({ type: 'Task' })
-  const createThing = useCreateThing()
+  const { data, isLoading } = useThings({ type: 'Task' })
 
   if (isLoading) return <div>Loading...</div>
-  if (error) return <div>Error: {error.message}</div>
-
-  const handleCreate = () => {
-    createThing.mutate({
-      ns: 'default',
-      type: 'Task',
-      name: 'New Task',
-      data: { status: 'todo', priority: 'medium' },
-    })
-  }
 
   return (
-    <div>
-      <button onClick={handleCreate} disabled={createThing.isLoading}>
-        Add Task
-      </button>
-      <ul>
-        {data?.data.map((task) => (
-          <li key={task.id}>{task.name}</li>
-        ))}
-      </ul>
-    </div>
+    <ul>
+      {data?.data.map((task) => (
+        <li key={task.id}>{task.name}</li>
+      ))}
+    </ul>
   )
 }
 ```
 
-## Core Concepts
-
-### Things
-
-Things are semantic entities (nouns) that form the foundation of your data model. Each Thing has:
+## Views
 
-- **Namespace (`ns`)**: Tenant or domain isolation (e.g., `"default"`, `"production"`)
-- **Type**: Entity classification (e.g., `"Task"`, `"User"`, `"Project"`)
-- **ID**: Unique identifier within namespace/type
-- **Data**: JSON-LD compatible payload with flexible schema
+Four view components for managing Things:
 
 ```tsx
-const { data } = useThings({ type: 'Task', nameSearch: 'urgent' })
-const { data: task } = useThing('default', 'Task', 'task-123')
+import {
+  DataBrowserView,   // Browse/search with filtering
+  DataGridView,      // Spreadsheet-style editing
+  DocumentEditorView, // Form-based editing
+  FunctionEditorView  // Execute functions
+} from '@mdxui/do/views'
 ```
 
-### Relationships
+## Hooks
 
-Relationships form a semantic knowledge graph connecting Things using 64+ built-in predicates across temporal, spatial, directional, relational, and causal categories.
+### Data Fetching
 
 ```tsx
-// Fetch relationships for an entity
-const { data } = useEntityRelationships(
-  { ns: 'default', type: 'Task', id: 'task-1', semanticId: 'default/Task/task-1' },
-  'both'
-)
-
-// Create a relationship
-const createRelationship = useCreateRelationship()
-createRelationship.mutate({
-  relationshipType: 'dependsOn',
-  from: { ns: 'default', type: 'Task', id: 'task-2', semanticId: 'default/Task/task-2' },
-  to: { ns: 'default', type: 'Task', id: 'task-1', semanticId: 'default/Task/task-1' },
-})
-```
-
-### Workflows
+import { useThings, useThing, useCreateThing } from '@mdxui/do'
 
-Workflows orchestrate multi-step business processes with support for:
+// List things
+const { data } = useThings({ type: 'Task' })
 
-- Event, schedule, manual, or webhook triggers
-- Function steps (Code, Generative, Agentic, Human)
-- Conditional branching and parallel execution
-- Saga pattern for compensation/rollback
+// Get single thing
+const { data } = useThing({ ns: 'default', type: 'Task', id: 'task-1' })
 
-```tsx
-const { data: workflows } = useWorkflows({ status: ['active'] })
-const triggerWorkflow = useTriggerWorkflow('workflow-id')
-
-// Trigger with input
-triggerWorkflow.mutate({ customerId: 'cust-123' })
+// Create thing
+const create = useCreateThing()
+create.mutate({ ns: 'default', type: 'Task', name: 'New Task', data: {} })
 ```
 
-### Agents
-
-Agents are autonomous AI workers derived from O*NET occupations and NAICS industries, creating 40,000+ potential agent types. They include:
-
-- System prompts and character bibles for persona
-- Tool access and guardrails for safety
-- Handoff rules for multi-agent coordination
-- Performance metrics and feedback collection
+### Discovery
 
 ```tsx
-const { data: agents } = useAgents({ roleCategory: ['engineer'], status: ['active'] })
-const executeAgent = useExecuteAgent('agent-id')
+import { useNamespaces, useTypes, useSchema } from '@mdxui/do'
 
-executeAgent.mutate({
-  task: 'Review this pull request for security issues',
-  context: { prUrl: 'https://github.com/...' },
-})
+const { data: namespaces } = useNamespaces()
+const { data: types } = useTypes()
+const { data: schema } = useSchema('Task')
 ```
 
-## Dual Mode Operation
-
-`@mdxui/do` supports two operational modes depending on your configuration:
+### State Management
 
-| Mode | Configuration | Use Case | Features |
-|------|---------------|----------|----------|
-| **REST API** | `apiEndpoint` only | Traditional server-rendered apps | Standard fetch, server-side caching |
-| **TanStack DB** | `apiEndpoint` + `doUrl` | Real-time collaborative apps | Local-first, WebSocket sync, offline support |
-
-### REST API Mode
+Endpoint and namespace state is managed via TanStack Query with localStorage persistence:
 
 ```tsx
-<DOProvider
-  config={{
-    apiEndpoint: 'https://api.example.do/admin',
-    authMethod: 'jwt',
-    authToken: 'your-token',
-    bindings: [],
-    realTimeUpdates: false,
-  }}
->
-  {children}
-</DOProvider>
-```
+import { useDOState, useEndpoint, useSetEndpoint } from '@mdxui/do'
 
-### TanStack DB Mode (Recommended)
+// Combined hook for all state
+const { endpoint, setEndpoint, namespace, setNamespace, recentEndpoints } = useDOState({
+  endpoint: 'https://api.example.do', // Required: fallback from config
+})
 
-```tsx
-<DOProvider
-  config={{
-    apiEndpoint: 'https://api.example.do/admin',
-    doUrl: 'wss://api.example.do/do/workspace',
-    authMethod: 'jwt',
-    authToken: 'your-token',
-    bindings: [],
-    realTimeUpdates: true,
-    collections: ['Task', 'User', 'Project'],
-    conflictStrategy: 'last-write-wins',
-    offline: { enabled: true, dbName: 'my-app-cache' },
-  }}
->
-  {children}
-</DOProvider>
+// Or use individual hooks
+const endpoint = useEndpoint('https://api.example.do')
+const { mutate: setEndpoint } = useSetEndpoint()
 ```
 
-## Configuration
-
-### DOAdminConfig
-
-| Property | Type | Required | Default | Description |
-|----------|------|----------|---------|-------------|
-| `apiEndpoint` | `string` | Yes | - | Base URL for REST API calls |
-| `doUrl` | `string` | No | - | WebSocket URL for Durable Object sync (enables TanStack DB mode) |
-| `authMethod` | `'jwt' \| 'api-key' \| 'oauth'` | Yes | - | Authentication method |
-| `authToken` | `string` | No | - | JWT token or API key |
-| `bindings` | `DOBinding[]` | Yes | - | Available Durable Object bindings |
-| `realTimeUpdates` | `boolean` | Yes | - | Enable real-time data updates |
-| `wsEndpoint` | `string` | No | - | Legacy WebSocket endpoint (prefer `doUrl`) |
-| `conflictStrategy` | `'last-write-wins' \| 'merge' \| ConflictResolver` | No | `'last-write-wins'` | How to resolve sync conflicts |
-| `offline` | `OfflineConfig` | No | - | Offline persistence settings |
-| `collections` | `string[]` | No | - | Entity types to auto-sync |
-
-### DOProviderProps
-
-| Property | Type | Required | Default | Description |
-|----------|------|----------|---------|-------------|
-| `config` | `DOAdminConfig` | Yes | - | Admin configuration |
-| `initialNamespace` | `string` | No | `'default'` | Starting namespace |
-| `userId` | `string` | No | - | Current user ID |
-| `children` | `ReactNode` | Yes | - | Child components |
-| `queryClient` | `QueryClient` | No | - | Custom TanStack Query client |
-
-## Available Hooks
-
-### Context Hooks
-
-| Hook | Description |
-|------|-------------|
-| `useDO()` | Access the DO context (config, namespace, connection status) |
-| `useDOUrls()` | Get derived URLs (rpcUrl, syncUrl, apiEndpoint) |
-| `useSyncStatus()` | Get current sync status (`'disconnected'`, `'connecting'`, `'syncing'`, `'synced'`, `'error'`) |
-
-### Things Hooks
-
-| Hook | Description |
-|------|-------------|
-| `useThings(filter?, sort?, pagination?)` | Fetch a paginated list of Things |
-| `useThing(ns, type, id)` | Fetch a single Thing by semantic ID |
-| `useThingVersions(ns, type, id)` | Fetch version history for a Thing |
-| `useTypeStats(ns, type)` | Fetch statistics for a Thing type |
-| `useCreateThing()` | Create a new Thing |
-| `useUpdateThing(ns, type, id)` | Update an existing Thing |
-| `useDeleteThing(ns, type, id)` | Soft or hard delete a Thing |
-
-### Relationships Hooks
-
-| Hook | Description |
-|------|-------------|
-| `useRelationships(filter?)` | Fetch relationships with optional filters |
-| `useEntityRelationships(entity, direction?)` | Fetch relationships for a specific entity |
-| `useGraphTraversal(entity, pattern)` | Traverse the graph from a starting entity |
-| `useGraphStats()` | Fetch graph statistics |
-| `useCreateRelationship()` | Create a new relationship |
-| `useDeleteRelationship()` | Delete a relationship |
-
-### Workflows Hooks
-
-| Hook | Description |
-|------|-------------|
-| `useWorkflows(filter?)` | Fetch workflows with optional filters |
-| `useWorkflow(id)` | Fetch a single workflow |
-| `useWorkflowExecutions(filter?)` | Fetch workflow executions |
-| `useWorkflowExecution(id)` | Fetch a single execution (auto-refetch while running) |
-| `useCreateWorkflow()` | Create a new workflow |
-| `useUpdateWorkflow(id)` | Update an existing workflow |
-| `useTriggerWorkflow(id)` | Manually trigger a workflow |
-| `useCancelExecution()` | Cancel a running execution |
-| `useDeleteWorkflow()` | Delete a workflow |
-
-### Agents Hooks
-
-| Hook | Description |
-|------|-------------|
-| `useAgents(filter?)` | Fetch agents with optional filters |
-| `useAgent(id)` | Fetch a single agent |
-| `useAgentMetrics(id, periodDays?)` | Fetch performance metrics for an agent |
-| `useAgentExecutions(filter?)` | Fetch agent executions |
-| `useAgentExecution(id)` | Fetch a single execution (auto-refetch while running) |
-| `useCreateAgent()` | Create a new agent |
-| `useUpdateAgent(id)` | Update an existing agent |
-| `useExecuteAgent(id)` | Execute an agent with a task |
-| `useSubmitAgentFeedback(executionId)` | Submit feedback for an execution |
-| `useDeleteAgent()` | Delete an agent |
-
-## Query Keys
-
-Each hook module exports query key factories for cache management:
+State persists across sessions via localStorage and automatically invalidates data queries when the endpoint changes.
 
-```tsx
-import { thingsKeys, relationshipsKeys, workflowsKeys, agentsKeys } from '@mdxui/do/hooks'
-import { useQueryClient } from '@tanstack/react-query'
-
-const queryClient = useQueryClient()
+## Architecture
 
-// Invalidate all things queries
-queryClient.invalidateQueries({ queryKey: thingsKeys.all })
+`DOApp` provides a complete admin dashboard with:
 
-// Invalidate a specific thing
-queryClient.invalidateQueries({ queryKey: thingsKeys.detail('default', 'Task', 'task-1') })
+- **TanStack Router** for client-side navigation
+- **WorkOS AuthKit** for authentication
+- **TanStack Query** for data fetching/caching
+- **capnweb** for WebSocket RPC to Durable Objects
 
-// Invalidate all workflow executions
-queryClient.invalidateQueries({ queryKey: workflowsKeys.executions() })
-```
+The auth flow:
+1. User signs in via WorkOS
+2. Access token is passed to `DOProvider`
+3. RPC calls include token as `?token=` query param
+4. Backend validates JWT
 
-## Components
+## Configuration
 
-The package includes pre-built UI components:
+### DOAdminConfig (for DOProvider)
 
-```tsx
-import { DOShell, DOSidebar, DOHeader, ThingsList, StatsCards, ErrorBoundary } from '@mdxui/do/components'
-```
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `apiEndpoint` | `string` | Yes | Base URL for API |
+| `authMethod` | `'none' \| 'jwt' \| 'api-key'` | Yes | Auth method |
+| `authToken` | `string` | No | JWT or API key |
+| `bindings` | `DOBinding[]` | Yes | DO bindings |
+| `realTimeUpdates` | `boolean` | Yes | Enable subscriptions |
+| `clientType` | `'capnweb' \| 'json-rpc'` | No | RPC client type |
 
-| Component | Description |
-|-----------|-------------|
-| `DOShell` | Main application shell with sidebar and header |
-| `DOSidebar` | Navigation sidebar with customizable items |
-| `DOHeader` | Application header with namespace selector |
-| `ThingsList` | Data table for displaying Things |
-| `StatsCards` | Dashboard statistics cards |
-| `ErrorBoundary` | Error boundary with fallback UI |
+### DOShellConfig (for DOApp)
 
-## Types
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `do` | `DOAdminConfig` | Yes | API config |
+| `identity` | `DOIdentity` | Yes | WorkOS auth config |
+| `branding` | `{ name?, logo? }` | No | Branding |
+| `basePath` | `string` | No | URL base path |
 
-Import types for TypeScript projects:
+## Exports
 
 ```tsx
-import type {
-  // Things
-  Thing,
-  ThingFilter,
-  ThingCreateInput,
-  ThingUpdateInput,
-  ThingQueryResult,
-
-  // Relationships
-  Relationship,
-  SemanticPredicate,
-  EntityReference,
-  GraphTraversalResult,
-
-  // Workflows
-  Workflow,
-  WorkflowExecution,
-  WorkflowStep,
-
-  // Agents
-  Agent,
-  AgentExecution,
-  AgentMetrics,
-
-  // Config
-  DOAdminConfig,
-  DOBinding,
-  SyncStatus,
-} from '@mdxui/do/types'
-```
-
-## Subpath Exports
-
-The package provides granular imports for tree-shaking:
+// Main
+import { DOProvider, useThings, DOApp } from '@mdxui/do'
 
-```tsx
-// Full package
-import { DOProvider, useThings, Thing } from '@mdxui/do'
+// App (routing, shell, auth)
+import { DOApp, DOShell, AuthGate } from '@mdxui/do/app'
 
-// Just providers
+// Providers
 import { DOProvider, useDO } from '@mdxui/do/providers'
 
-// Just hooks
-import { useThings, useAgents } from '@mdxui/do/hooks'
-
-// Just components
-import { DOShell, ThingsList } from '@mdxui/do/components'
-
-// Just types
-import type { Thing, Agent } from '@mdxui/do/types'
-```
+// Hooks
+import { useThings, useCreateThing } from '@mdxui/do/hooks'
 
-## Error Handling
+// State (TanStack Query-based)
+import { useDOState, useEndpoint, useSetEndpoint, useNamespace } from '@mdxui/do'
 
-The package provides type guards for handling API errors:
+// Views
+import { DataBrowserView, DataGridView } from '@mdxui/do/views'
 
-```tsx
-import { isValidationErrorData, isNotFoundError, isRateLimitError, isAppError } from '@mdxui/do/types'
-
-try {
-  await createThing.mutateAsync({ /* ... */ })
-} catch (error) {
-  if (isAppError(error)) {
-    if (isValidationErrorData(error)) {
-      // Handle validation errors (API response data)
-      error.errors.forEach(e => console.log(e.field, e.message))
-    } else if (isNotFoundError(error)) {
-      // Handle not found
-      console.log(`${error.resourceType}/${error.resourceId} not found`)
-    } else if (isRateLimitError(error)) {
-      // Handle rate limiting
-      console.log(`Retry after ${error.retryAfter}ms`)
-    }
-  }
-}
+// Types
+import type { Thing, DOAdminConfig } from '@mdxui/do/types'
 ```
 
 ## License