@mdxui/do 2.1.1

package/README.md

@@ -0,0 +1,412 @@
+# @mdxui/do
+
+[![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.
+
+## Installation
+
+```bash
+npm install @mdxui/do
+# or
+pnpm add @mdxui/do
+# or
+yarn add @mdxui/do
+```
+
+### Peer Dependencies
+
+```bash
+npm install react react-dom
+```
+
+## Quick Start
+
+Wrap your application with `DOProvider` and start using hooks to fetch and mutate data:
+
+```tsx
+import { DOProvider, useThings, useCreateThing } 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',
+        bindings: [],
+        realTimeUpdates: true,
+        collections: ['Task', 'User', 'Project'],
+      }}
+      initialNamespace="default"
+    >
+      <TaskList />
+    </DOProvider>
+  )
+}
+
+function TaskList() {
+  const { data, isLoading, error } = useThings({ type: 'Task' })
+  const createThing = useCreateThing()
+
+  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>
+  )
+}
+```
+
+## Core Concepts
+
+### Things
+
+Things are semantic entities (nouns) that form the foundation of your data model. Each Thing has:
+
+- **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
+
+```tsx
+const { data } = useThings({ type: 'Task', nameSearch: 'urgent' })
+const { data: task } = useThing('default', 'Task', 'task-123')
+```
+
+### Relationships
+
+Relationships form a semantic knowledge graph connecting Things using 64+ built-in predicates across temporal, spatial, directional, relational, and causal categories.
+
+```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
+
+Workflows orchestrate multi-step business processes with support for:
+
+- Event, schedule, manual, or webhook triggers
+- Function steps (Code, Generative, Agentic, Human)
+- Conditional branching and parallel execution
+- Saga pattern for compensation/rollback
+
+```tsx
+const { data: workflows } = useWorkflows({ status: ['active'] })
+const triggerWorkflow = useTriggerWorkflow('workflow-id')
+
+// Trigger with input
+triggerWorkflow.mutate({ customerId: 'cust-123' })
+```
+
+### 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
+
+```tsx
+const { data: agents } = useAgents({ roleCategory: ['engineer'], status: ['active'] })
+const executeAgent = useExecuteAgent('agent-id')
+
+executeAgent.mutate({
+  task: 'Review this pull request for security issues',
+  context: { prUrl: 'https://github.com/...' },
+})
+```
+
+## Dual Mode Operation
+
+`@mdxui/do` supports two operational modes depending on your configuration:
+
+| 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
+
+```tsx
+<DOProvider
+  config={{
+    apiEndpoint: 'https://api.example.do/admin',
+    authMethod: 'jwt',
+    authToken: 'your-token',
+    bindings: [],
+    realTimeUpdates: false,
+  }}
+>
+  {children}
+</DOProvider>
+```
+
+### TanStack DB Mode (Recommended)
+
+```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>
+```
+
+## 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:
+
+```tsx
+import { thingsKeys, relationshipsKeys, workflowsKeys, agentsKeys } from '@mdxui/do/hooks'
+import { useQueryClient } from '@tanstack/react-query'
+
+const queryClient = useQueryClient()
+
+// Invalidate all things queries
+queryClient.invalidateQueries({ queryKey: thingsKeys.all })
+
+// Invalidate a specific thing
+queryClient.invalidateQueries({ queryKey: thingsKeys.detail('default', 'Task', 'task-1') })
+
+// Invalidate all workflow executions
+queryClient.invalidateQueries({ queryKey: workflowsKeys.executions() })
+```
+
+## Components
+
+The package includes pre-built UI components:
+
+```tsx
+import { DOShell, DOSidebar, DOHeader, ThingsList, StatsCards, ErrorBoundary } from '@mdxui/do/components'
+```
+
+| 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 |
+
+## Types
+
+Import types for TypeScript projects:
+
+```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:
+
+```tsx
+// Full package
+import { DOProvider, useThings, Thing } from '@mdxui/do'
+
+// Just 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'
+```
+
+## Error Handling
+
+The package provides type guards for handling API errors:
+
+```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`)
+    }
+  }
+}
+```
+
+## License
+
+MIT