diff --git a/apps/docs/app/[lang]/docs/[[...slug]]/page.tsx b/apps/docs/app/[lang]/docs/[[...slug]]/page.tsx index e68476651..3a7fed801 100644 --- a/apps/docs/app/[lang]/docs/[[...slug]]/page.tsx +++ b/apps/docs/app/[lang]/docs/[[...slug]]/page.tsx @@ -5,6 +5,7 @@ import { notFound } from 'next/navigation'; import defaultMdxComponents from 'fumadocs-ui/mdx'; import { Step, Steps } from 'fumadocs-ui/components/steps'; import { File, Folder, Files } from 'fumadocs-ui/components/files'; +import { Tab, Tabs } from 'fumadocs-ui/components/tabs'; const components = { ...defaultMdxComponents, @@ -14,6 +15,8 @@ const components = { Folder, Files, FileTree: Files, + Tab, + Tabs, }; export default async function Page(props: { diff --git a/apps/docs/next.config.mjs b/apps/docs/next.config.mjs index 622c0829a..d4af6c5da 100644 --- a/apps/docs/next.config.mjs +++ b/apps/docs/next.config.mjs @@ -18,20 +18,16 @@ const config = { }, ], }, - experimental: { - turbo: { - resolveAlias: { - 'fumadocs-ui/components/callout': 'fumadocs-ui/dist/components/callout.js', - }, - }, - }, webpack: (config, { isServer }) => { // Resolve the fumadocs virtual collection import to the local .source directory config.resolve = config.resolve || {}; config.resolve.alias = { ...(config.resolve.alias || {}), 'fumadocs-mdx:collections': path.resolve(__dirname, '.source'), - 'fumadocs-ui/components/callout$': path.resolve(__dirname, '../../node_modules/fumadocs-ui/dist/components/callout.js'), + 'fumadocs-ui/components/callout$': path.resolve(__dirname, './node_modules/fumadocs-ui/dist/components/callout.js'), + 'fumadocs-ui/components/card$': path.resolve(__dirname, './node_modules/fumadocs-ui/dist/components/card.js'), + 'fumadocs-ui/components/tabs$': path.resolve(__dirname, './node_modules/fumadocs-ui/dist/components/tabs.js'), + 'lucide-react$': path.resolve(__dirname, './node_modules/lucide-react/dist/cjs/lucide-react.js'), }; return config; }, diff --git a/apps/docs/package.json b/apps/docs/package.json index 5287b6583..4fe34834b 100644 --- a/apps/docs/package.json +++ b/apps/docs/package.json @@ -5,7 +5,7 @@ "description": "ObjectStack Protocol Documentation Site", "scripts": { "dev": "next dev", - "build": "NEXT_PRIVATE_BUILD_WORKER=1 next build", + "build": "next build", "site:start": "next start", "site:lint": "next lint" }, diff --git a/content/docs/references/ai/agent.mdx b/content/docs/references/ai/agent.mdx new file mode 100644 index 000000000..619aa6aa2 --- /dev/null +++ b/content/docs/references/ai/agent.mdx @@ -0,0 +1,77 @@ +--- +title: Agent +description: Agent protocol schemas +--- + +# Agent + + +**Source:** `packages/spec/src/ai/agent.zod.ts` + + +## TypeScript Usage + +```typescript +import { AIKnowledgeSchema, AIModelConfigSchema, AIToolSchema, AgentSchema } from '@objectstack/spec/ai'; +import type { AIKnowledge, AIModelConfig, AITool, Agent } from '@objectstack/spec/ai'; + +// Validate data +const result = AIKnowledgeSchema.parse(data); +``` + +--- + +## AIKnowledge + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **topics** | `string[]` | ✅ | Topics/Tags to recruit knowledge from | +| **indexes** | `string[]` | ✅ | Vector Store Indexes | + +--- + +## AIModelConfig + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **provider** | `Enum<'openai' \| 'azure_openai' \| 'anthropic' \| 'local'>` | optional | | +| **model** | `string` | ✅ | Model name (e.g. gpt-4, claude-3-opus) | +| **temperature** | `number` | optional | | +| **maxTokens** | `number` | optional | | +| **topP** | `number` | optional | | + +--- + +## AITool + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **type** | `Enum<'action' \| 'flow' \| 'query' \| 'vector_search'>` | ✅ | | +| **name** | `string` | ✅ | Reference name (Action Name, Flow Name) | +| **description** | `string` | optional | Override description for the LLM | + +--- + +## Agent + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Agent unique identifier | +| **label** | `string` | ✅ | Agent display name | +| **avatar** | `string` | optional | | +| **role** | `string` | ✅ | The persona/role (e.g. "Senior Support Engineer") | +| **instructions** | `string` | ✅ | System Prompt / Prime Directives | +| **model** | `object` | optional | | +| **tools** | `object[]` | optional | Available tools | +| **knowledge** | `object` | optional | RAG access | +| **active** | `boolean` | optional | | +| **access** | `string[]` | optional | Who can chat with this agent | + diff --git a/content/docs/references/ai/agent/AIKnowledge.mdx b/content/docs/references/ai/agent/AIKnowledge.mdx deleted file mode 100644 index a95abc12b..000000000 --- a/content/docs/references/ai/agent/AIKnowledge.mdx +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: AIKnowledge -description: AIKnowledge Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **topics** | `string[]` | ✅ | Topics/Tags to recruit knowledge from | -| **indexes** | `string[]` | ✅ | Vector Store Indexes | diff --git a/content/docs/references/ai/agent/AIModelConfig.mdx b/content/docs/references/ai/agent/AIModelConfig.mdx deleted file mode 100644 index d3f685795..000000000 --- a/content/docs/references/ai/agent/AIModelConfig.mdx +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: AIModelConfig -description: AIModelConfig Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **provider** | `Enum<'openai' \| 'azure_openai' \| 'anthropic' \| 'local'>` | optional | | -| **model** | `string` | ✅ | Model name (e.g. gpt-4, claude-3-opus) | -| **temperature** | `number` | optional | | -| **maxTokens** | `number` | optional | | -| **topP** | `number` | optional | | diff --git a/content/docs/references/ai/agent/AITool.mdx b/content/docs/references/ai/agent/AITool.mdx deleted file mode 100644 index fc872724d..000000000 --- a/content/docs/references/ai/agent/AITool.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: AITool -description: AITool Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `Enum<'action' \| 'flow' \| 'query' \| 'vector_search'>` | ✅ | | -| **name** | `string` | ✅ | Reference name (Action Name, Flow Name) | -| **description** | `string` | optional | Override description for the LLM | diff --git a/content/docs/references/ai/agent/Agent.mdx b/content/docs/references/ai/agent/Agent.mdx deleted file mode 100644 index 63ecbb9c3..000000000 --- a/content/docs/references/ai/agent/Agent.mdx +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Agent -description: Agent Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Agent unique identifier | -| **label** | `string` | ✅ | Agent display name | -| **avatar** | `string` | optional | | -| **role** | `string` | ✅ | The persona/role (e.g. "Senior Support Engineer") | -| **instructions** | `string` | ✅ | System Prompt / Prime Directives | -| **model** | `object` | optional | | -| **tools** | `object[]` | optional | Available tools | -| **knowledge** | `object` | optional | RAG access | -| **active** | `boolean` | optional | | -| **access** | `string[]` | optional | Who can chat with this agent | diff --git a/content/docs/references/ai/agent/meta.json b/content/docs/references/ai/agent/meta.json deleted file mode 100644 index 6fbb63fe0..000000000 --- a/content/docs/references/ai/agent/meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "title": "Agent" -} \ No newline at end of file diff --git a/content/docs/references/ai/conversation.mdx b/content/docs/references/ai/conversation.mdx new file mode 100644 index 000000000..0fd508b7b --- /dev/null +++ b/content/docs/references/ai/conversation.mdx @@ -0,0 +1,256 @@ +--- +title: Conversation +description: Conversation protocol schemas +--- + +# Conversation + + +**Source:** `packages/spec/src/ai/conversation.zod.ts` + + +## TypeScript Usage + +```typescript +import { ConversationAnalyticsSchema, ConversationContextSchema, ConversationMessageSchema, ConversationSessionSchema, ConversationSummarySchema, FunctionCallSchema, MessageContentSchema, MessageContentTypeSchema, MessagePruningEventSchema, MessageRoleSchema, TokenBudgetConfigSchema, TokenBudgetStrategySchema, TokenUsageStatsSchema, ToolCallSchema } from '@objectstack/spec/ai'; +import type { ConversationAnalytics, ConversationContext, ConversationMessage, ConversationSession, ConversationSummary, FunctionCall, MessageContent, MessageContentType, MessagePruningEvent, MessageRole, TokenBudgetConfig, TokenBudgetStrategy, TokenUsageStats, ToolCall } from '@objectstack/spec/ai'; + +// Validate data +const result = ConversationAnalyticsSchema.parse(data); +``` + +--- + +## ConversationAnalytics + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **sessionId** | `string` | ✅ | | +| **totalMessages** | `integer` | ✅ | | +| **userMessages** | `integer` | ✅ | | +| **assistantMessages** | `integer` | ✅ | | +| **systemMessages** | `integer` | ✅ | | +| **totalTokens** | `integer` | ✅ | | +| **averageTokensPerMessage** | `number` | ✅ | | +| **peakTokenUsage** | `integer` | ✅ | | +| **pruningEvents** | `integer` | optional | | +| **summarizationEvents** | `integer` | optional | | +| **tokensSavedByPruning** | `integer` | optional | | +| **tokensSavedBySummarization** | `integer` | optional | | +| **duration** | `number` | optional | Session duration in seconds | +| **firstMessageAt** | `string` | optional | ISO 8601 timestamp | +| **lastMessageAt** | `string` | optional | ISO 8601 timestamp | + +--- + +## ConversationContext + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **sessionId** | `string` | ✅ | Conversation session ID | +| **userId** | `string` | optional | User identifier | +| **agentId** | `string` | optional | AI agent identifier | +| **object** | `string` | optional | Related object (e.g., "case", "project") | +| **recordId** | `string` | optional | Related record ID | +| **scope** | `Record` | optional | Additional context scope | +| **systemMessage** | `string` | optional | System prompt/instructions | +| **metadata** | `Record` | optional | | + +--- + +## ConversationMessage + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | ✅ | Unique message ID | +| **timestamp** | `string` | ✅ | ISO 8601 timestamp | +| **role** | `Enum<'system' \| 'user' \| 'assistant' \| 'function' \| 'tool'>` | ✅ | | +| **content** | `string \| object[]` | ✅ | Message content (text or multimodal) | +| **functionCall** | `object` | optional | Legacy function call | +| **toolCalls** | `object[]` | optional | Tool calls | +| **toolCallId** | `string` | optional | Tool call ID this message responds to | +| **name** | `string` | optional | Name of the function/user | +| **tokens** | `object` | optional | Token usage for this message | +| **pinned** | `boolean` | optional | Prevent removal during pruning | +| **importance** | `number` | optional | Importance score for pruning | +| **embedding** | `number[]` | optional | Vector embedding for semantic search | +| **metadata** | `Record` | optional | | + +--- + +## ConversationSession + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | ✅ | Unique session ID | +| **name** | `string` | optional | Session name/title | +| **context** | `object` | ✅ | | +| **modelId** | `string` | optional | AI model ID | +| **tokenBudget** | `object` | ✅ | | +| **messages** | `object[]` | optional | | +| **tokens** | `object` | optional | | +| **status** | `Enum<'active' \| 'paused' \| 'completed' \| 'archived'>` | optional | | +| **createdAt** | `string` | ✅ | ISO 8601 timestamp | +| **updatedAt** | `string` | ✅ | ISO 8601 timestamp | +| **expiresAt** | `string` | optional | ISO 8601 timestamp | +| **tags** | `string[]` | optional | | +| **metadata** | `Record` | optional | | + +--- + +## ConversationSummary + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **summary** | `string` | ✅ | Conversation summary | +| **keyPoints** | `string[]` | optional | Key discussion points | +| **originalTokens** | `integer` | ✅ | Original token count | +| **summaryTokens** | `integer` | ✅ | Summary token count | +| **tokensSaved** | `integer` | ✅ | Tokens saved | +| **messageRange** | `object` | ✅ | Range of messages summarized | +| **generatedAt** | `string` | ✅ | ISO 8601 timestamp | +| **modelId** | `string` | optional | Model used for summarization | + +--- + +## FunctionCall + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Function name | +| **arguments** | `string` | ✅ | JSON string of function arguments | +| **result** | `string` | optional | Function execution result | + +--- + +## MessageContent + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **type** | `Enum<'text' \| 'image' \| 'file' \| 'code' \| 'structured'>` | optional | | +| **text** | `string` | optional | Text content | +| **imageUrl** | `string` | optional | Image URL for vision models | +| **fileUrl** | `string` | optional | File attachment URL | +| **mimeType** | `string` | optional | MIME type for files | +| **metadata** | `Record` | optional | Additional metadata | + +--- + +## MessageContentType + +### Allowed Values + +* `text` +* `image` +* `file` +* `code` +* `structured` + +--- + +## MessagePruningEvent + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **timestamp** | `string` | ✅ | ISO 8601 timestamp | +| **strategy** | `Enum<'fifo' \| 'importance' \| 'semantic' \| 'sliding_window' \| 'summary'>` | ✅ | | +| **reason** | `string` | ✅ | Reason for pruning | +| **prunedMessages** | `object[]` | ✅ | | +| **tokensFreed** | `integer` | ✅ | | +| **messagesRemoved** | `integer` | ✅ | | +| **remainingTokens** | `integer` | ✅ | | +| **remainingMessages** | `integer` | ✅ | | + +--- + +## MessageRole + +### Allowed Values + +* `system` +* `user` +* `assistant` +* `function` +* `tool` + +--- + +## TokenBudgetConfig + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **maxTokens** | `integer` | ✅ | Maximum total tokens | +| **maxPromptTokens** | `integer` | optional | Max tokens for prompt | +| **maxCompletionTokens** | `integer` | optional | Max tokens for completion | +| **reserveTokens** | `integer` | optional | Reserve tokens for system messages | +| **bufferPercentage** | `number` | optional | Buffer percentage (0.1 = 10%) | +| **strategy** | `Enum<'fifo' \| 'importance' \| 'semantic' \| 'sliding_window' \| 'summary'>` | optional | | +| **slidingWindowSize** | `integer` | optional | Number of recent messages to keep | +| **minImportanceScore** | `number` | optional | Minimum importance to keep | +| **semanticThreshold** | `number` | optional | Semantic similarity threshold | +| **enableSummarization** | `boolean` | optional | Enable context summarization | +| **summarizationThreshold** | `integer` | optional | Trigger summarization at N tokens | +| **summaryModel** | `string` | optional | Model ID for summarization | +| **warnThreshold** | `number` | optional | Warn at % of budget (0.8 = 80%) | + +--- + +## TokenBudgetStrategy + +### Allowed Values + +* `fifo` +* `importance` +* `semantic` +* `sliding_window` +* `summary` + +--- + +## TokenUsageStats + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **promptTokens** | `integer` | optional | | +| **completionTokens** | `integer` | optional | | +| **totalTokens** | `integer` | optional | | +| **budgetLimit** | `integer` | ✅ | | +| **budgetUsed** | `integer` | optional | | +| **budgetRemaining** | `integer` | ✅ | | +| **budgetPercentage** | `number` | ✅ | Usage as percentage of budget | +| **messageCount** | `integer` | optional | | +| **prunedMessageCount** | `integer` | optional | | +| **summarizedMessageCount** | `integer` | optional | | + +--- + +## ToolCall + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | ✅ | Tool call ID | +| **type** | `Enum<'function'>` | optional | | +| **function** | `object` | ✅ | | + diff --git a/content/docs/references/ai/conversation/ConversationAnalytics.mdx b/content/docs/references/ai/conversation/ConversationAnalytics.mdx deleted file mode 100644 index 2c715617a..000000000 --- a/content/docs/references/ai/conversation/ConversationAnalytics.mdx +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: ConversationAnalytics -description: ConversationAnalytics Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **sessionId** | `string` | ✅ | | -| **totalMessages** | `integer` | ✅ | | -| **userMessages** | `integer` | ✅ | | -| **assistantMessages** | `integer` | ✅ | | -| **systemMessages** | `integer` | ✅ | | -| **totalTokens** | `integer` | ✅ | | -| **averageTokensPerMessage** | `number` | ✅ | | -| **peakTokenUsage** | `integer` | ✅ | | -| **pruningEvents** | `integer` | optional | | -| **summarizationEvents** | `integer` | optional | | -| **tokensSavedByPruning** | `integer` | optional | | -| **tokensSavedBySummarization** | `integer` | optional | | -| **duration** | `number` | optional | Session duration in seconds | -| **firstMessageAt** | `string` | optional | ISO 8601 timestamp | -| **lastMessageAt** | `string` | optional | ISO 8601 timestamp | diff --git a/content/docs/references/ai/conversation/ConversationContext.mdx b/content/docs/references/ai/conversation/ConversationContext.mdx deleted file mode 100644 index 8ffd326fd..000000000 --- a/content/docs/references/ai/conversation/ConversationContext.mdx +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: ConversationContext -description: ConversationContext Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **sessionId** | `string` | ✅ | Conversation session ID | -| **userId** | `string` | optional | User identifier | -| **agentId** | `string` | optional | AI agent identifier | -| **object** | `string` | optional | Related object (e.g., "case", "project") | -| **recordId** | `string` | optional | Related record ID | -| **scope** | `Record` | optional | Additional context scope | -| **systemMessage** | `string` | optional | System prompt/instructions | -| **metadata** | `Record` | optional | | diff --git a/content/docs/references/ai/conversation/ConversationMessage.mdx b/content/docs/references/ai/conversation/ConversationMessage.mdx deleted file mode 100644 index abc8cf19c..000000000 --- a/content/docs/references/ai/conversation/ConversationMessage.mdx +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: ConversationMessage -description: ConversationMessage Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Unique message ID | -| **timestamp** | `string` | ✅ | ISO 8601 timestamp | -| **role** | `Enum<'system' \| 'user' \| 'assistant' \| 'function' \| 'tool'>` | ✅ | | -| **content** | `string \| object[]` | ✅ | Message content (text or multimodal) | -| **functionCall** | `object` | optional | Legacy function call | -| **toolCalls** | `object[]` | optional | Tool calls | -| **toolCallId** | `string` | optional | Tool call ID this message responds to | -| **name** | `string` | optional | Name of the function/user | -| **tokens** | `object` | optional | Token usage for this message | -| **pinned** | `boolean` | optional | Prevent removal during pruning | -| **importance** | `number` | optional | Importance score for pruning | -| **embedding** | `number[]` | optional | Vector embedding for semantic search | -| **metadata** | `Record` | optional | | diff --git a/content/docs/references/ai/conversation/ConversationSession.mdx b/content/docs/references/ai/conversation/ConversationSession.mdx deleted file mode 100644 index 769c0f214..000000000 --- a/content/docs/references/ai/conversation/ConversationSession.mdx +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: ConversationSession -description: ConversationSession Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Unique session ID | -| **name** | `string` | optional | Session name/title | -| **context** | `object` | ✅ | | -| **modelId** | `string` | optional | AI model ID | -| **tokenBudget** | `object` | ✅ | | -| **messages** | `object[]` | optional | | -| **tokens** | `object` | optional | | -| **status** | `Enum<'active' \| 'paused' \| 'completed' \| 'archived'>` | optional | | -| **createdAt** | `string` | ✅ | ISO 8601 timestamp | -| **updatedAt** | `string` | ✅ | ISO 8601 timestamp | -| **expiresAt** | `string` | optional | ISO 8601 timestamp | -| **tags** | `string[]` | optional | | -| **metadata** | `Record` | optional | | diff --git a/content/docs/references/ai/conversation/ConversationSummary.mdx b/content/docs/references/ai/conversation/ConversationSummary.mdx deleted file mode 100644 index 8f5eff0d4..000000000 --- a/content/docs/references/ai/conversation/ConversationSummary.mdx +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: ConversationSummary -description: ConversationSummary Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **summary** | `string` | ✅ | Conversation summary | -| **keyPoints** | `string[]` | optional | Key discussion points | -| **originalTokens** | `integer` | ✅ | Original token count | -| **summaryTokens** | `integer` | ✅ | Summary token count | -| **tokensSaved** | `integer` | ✅ | Tokens saved | -| **messageRange** | `object` | ✅ | Range of messages summarized | -| **generatedAt** | `string` | ✅ | ISO 8601 timestamp | -| **modelId** | `string` | optional | Model used for summarization | diff --git a/content/docs/references/ai/conversation/FunctionCall.mdx b/content/docs/references/ai/conversation/FunctionCall.mdx deleted file mode 100644 index cf5f10605..000000000 --- a/content/docs/references/ai/conversation/FunctionCall.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: FunctionCall -description: FunctionCall Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Function name | -| **arguments** | `string` | ✅ | JSON string of function arguments | -| **result** | `string` | optional | Function execution result | diff --git a/content/docs/references/ai/conversation/MessageContent.mdx b/content/docs/references/ai/conversation/MessageContent.mdx deleted file mode 100644 index e7e9c6212..000000000 --- a/content/docs/references/ai/conversation/MessageContent.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: MessageContent -description: MessageContent Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `Enum<'text' \| 'image' \| 'file' \| 'code' \| 'structured'>` | optional | | -| **text** | `string` | optional | Text content | -| **imageUrl** | `string` | optional | Image URL for vision models | -| **fileUrl** | `string` | optional | File attachment URL | -| **mimeType** | `string` | optional | MIME type for files | -| **metadata** | `Record` | optional | Additional metadata | diff --git a/content/docs/references/ai/conversation/MessageContentType.mdx b/content/docs/references/ai/conversation/MessageContentType.mdx deleted file mode 100644 index 234ce5b5b..000000000 --- a/content/docs/references/ai/conversation/MessageContentType.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: MessageContentType -description: MessageContentType Schema Reference ---- - -## Allowed Values - -* `text` -* `image` -* `file` -* `code` -* `structured` \ No newline at end of file diff --git a/content/docs/references/ai/conversation/MessagePruningEvent.mdx b/content/docs/references/ai/conversation/MessagePruningEvent.mdx deleted file mode 100644 index eb1528348..000000000 --- a/content/docs/references/ai/conversation/MessagePruningEvent.mdx +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: MessagePruningEvent -description: MessagePruningEvent Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **timestamp** | `string` | ✅ | ISO 8601 timestamp | -| **strategy** | `Enum<'fifo' \| 'importance' \| 'semantic' \| 'sliding_window' \| 'summary'>` | ✅ | | -| **reason** | `string` | ✅ | Reason for pruning | -| **prunedMessages** | `object[]` | ✅ | | -| **tokensFreed** | `integer` | ✅ | | -| **messagesRemoved** | `integer` | ✅ | | -| **remainingTokens** | `integer` | ✅ | | -| **remainingMessages** | `integer` | ✅ | | diff --git a/content/docs/references/ai/conversation/MessageRole.mdx b/content/docs/references/ai/conversation/MessageRole.mdx deleted file mode 100644 index a24e4016d..000000000 --- a/content/docs/references/ai/conversation/MessageRole.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: MessageRole -description: MessageRole Schema Reference ---- - -## Allowed Values - -* `system` -* `user` -* `assistant` -* `function` -* `tool` \ No newline at end of file diff --git a/content/docs/references/ai/conversation/TokenBudgetConfig.mdx b/content/docs/references/ai/conversation/TokenBudgetConfig.mdx deleted file mode 100644 index f9c01c073..000000000 --- a/content/docs/references/ai/conversation/TokenBudgetConfig.mdx +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: TokenBudgetConfig -description: TokenBudgetConfig Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **maxTokens** | `integer` | ✅ | Maximum total tokens | -| **maxPromptTokens** | `integer` | optional | Max tokens for prompt | -| **maxCompletionTokens** | `integer` | optional | Max tokens for completion | -| **reserveTokens** | `integer` | optional | Reserve tokens for system messages | -| **bufferPercentage** | `number` | optional | Buffer percentage (0.1 = 10%) | -| **strategy** | `Enum<'fifo' \| 'importance' \| 'semantic' \| 'sliding_window' \| 'summary'>` | optional | | -| **slidingWindowSize** | `integer` | optional | Number of recent messages to keep | -| **minImportanceScore** | `number` | optional | Minimum importance to keep | -| **semanticThreshold** | `number` | optional | Semantic similarity threshold | -| **enableSummarization** | `boolean` | optional | Enable context summarization | -| **summarizationThreshold** | `integer` | optional | Trigger summarization at N tokens | -| **summaryModel** | `string` | optional | Model ID for summarization | -| **warnThreshold** | `number` | optional | Warn at % of budget (0.8 = 80%) | diff --git a/content/docs/references/ai/conversation/TokenBudgetStrategy.mdx b/content/docs/references/ai/conversation/TokenBudgetStrategy.mdx deleted file mode 100644 index 4070b4693..000000000 --- a/content/docs/references/ai/conversation/TokenBudgetStrategy.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: TokenBudgetStrategy -description: TokenBudgetStrategy Schema Reference ---- - -## Allowed Values - -* `fifo` -* `importance` -* `semantic` -* `sliding_window` -* `summary` \ No newline at end of file diff --git a/content/docs/references/ai/conversation/TokenUsageStats.mdx b/content/docs/references/ai/conversation/TokenUsageStats.mdx deleted file mode 100644 index 9d4a776b9..000000000 --- a/content/docs/references/ai/conversation/TokenUsageStats.mdx +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: TokenUsageStats -description: TokenUsageStats Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **promptTokens** | `integer` | optional | | -| **completionTokens** | `integer` | optional | | -| **totalTokens** | `integer` | optional | | -| **budgetLimit** | `integer` | ✅ | | -| **budgetUsed** | `integer` | optional | | -| **budgetRemaining** | `integer` | ✅ | | -| **budgetPercentage** | `number` | ✅ | Usage as percentage of budget | -| **messageCount** | `integer` | optional | | -| **prunedMessageCount** | `integer` | optional | | -| **summarizedMessageCount** | `integer` | optional | | diff --git a/content/docs/references/ai/conversation/ToolCall.mdx b/content/docs/references/ai/conversation/ToolCall.mdx deleted file mode 100644 index 8c31d637a..000000000 --- a/content/docs/references/ai/conversation/ToolCall.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: ToolCall -description: ToolCall Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Tool call ID | -| **type** | `Enum<'function'>` | optional | | -| **function** | `object` | ✅ | | diff --git a/content/docs/references/ai/conversation/meta.json b/content/docs/references/ai/conversation/meta.json deleted file mode 100644 index 6a8728d4b..000000000 --- a/content/docs/references/ai/conversation/meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "title": "Conversation" -} \ No newline at end of file diff --git a/content/docs/references/ai/cost.mdx b/content/docs/references/ai/cost.mdx new file mode 100644 index 000000000..d2cc5d1e5 --- /dev/null +++ b/content/docs/references/ai/cost.mdx @@ -0,0 +1,318 @@ +--- +title: Cost +description: Cost protocol schemas +--- + +# Cost + + +**Source:** `packages/spec/src/ai/cost.zod.ts` + + +## TypeScript Usage + +```typescript +import { BillingPeriodSchema, BudgetLimitSchema, BudgetStatusSchema, BudgetTypeSchema, CostAlertSchema, CostAlertTypeSchema, CostAnalyticsSchema, CostBreakdownDimensionSchema, CostBreakdownEntrySchema, CostEntrySchema, CostMetricTypeSchema, CostOptimizationRecommendationSchema, CostQueryFiltersSchema, CostReportSchema } from '@objectstack/spec/ai'; +import type { BillingPeriod, BudgetLimit, BudgetStatus, BudgetType, CostAlert, CostAlertType, CostAnalytics, CostBreakdownDimension, CostBreakdownEntry, CostEntry, CostMetricType, CostOptimizationRecommendation, CostQueryFilters, CostReport } from '@objectstack/spec/ai'; + +// Validate data +const result = BillingPeriodSchema.parse(data); +``` + +--- + +## BillingPeriod + +### Allowed Values + +* `hourly` +* `daily` +* `weekly` +* `monthly` +* `quarterly` +* `yearly` +* `custom` + +--- + +## BudgetLimit + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **type** | `Enum<'global' \| 'user' \| 'agent' \| 'object' \| 'project' \| 'department'>` | ✅ | | +| **scope** | `string` | optional | Scope identifier (userId, agentId, etc.) | +| **maxCost** | `number` | ✅ | Maximum cost limit | +| **currency** | `string` | optional | | +| **period** | `Enum<'hourly' \| 'daily' \| 'weekly' \| 'monthly' \| 'quarterly' \| 'yearly' \| 'custom'>` | ✅ | | +| **customPeriodDays** | `integer` | optional | Custom period in days | +| **softLimit** | `number` | optional | Soft limit for warnings | +| **warnThresholds** | `number[]` | optional | Warning thresholds (e.g., [0.5, 0.8, 0.95]) | +| **enforced** | `boolean` | optional | Block requests when exceeded | +| **gracePeriodSeconds** | `integer` | optional | Grace period after limit exceeded | +| **allowRollover** | `boolean` | optional | Allow unused budget to rollover | +| **maxRolloverPercentage** | `number` | optional | Max rollover as % of limit | +| **name** | `string` | optional | Budget name | +| **description** | `string` | optional | | +| **active** | `boolean` | optional | | +| **tags** | `string[]` | optional | | + +--- + +## BudgetStatus + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **budgetId** | `string` | ✅ | | +| **type** | `Enum<'global' \| 'user' \| 'agent' \| 'object' \| 'project' \| 'department'>` | ✅ | | +| **scope** | `string` | optional | | +| **periodStart** | `string` | ✅ | ISO 8601 timestamp | +| **periodEnd** | `string` | ✅ | ISO 8601 timestamp | +| **currentCost** | `number` | optional | | +| **maxCost** | `number` | ✅ | | +| **currency** | `string` | optional | | +| **percentageUsed** | `number` | ✅ | Usage as percentage (can exceed 1.0 if over budget) | +| **remainingCost** | `number` | ✅ | Remaining budget (can be negative if exceeded) | +| **isExceeded** | `boolean` | optional | | +| **isWarning** | `boolean` | optional | | +| **projectedCost** | `number` | optional | Projected cost for period | +| **projectedOverage** | `number` | optional | Projected overage | +| **lastUpdated** | `string` | ✅ | ISO 8601 timestamp | + +--- + +## BudgetType + +### Allowed Values + +* `global` +* `user` +* `agent` +* `object` +* `project` +* `department` + +--- + +## CostAlert + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | ✅ | | +| **timestamp** | `string` | ✅ | ISO 8601 timestamp | +| **type** | `Enum<'threshold_warning' \| 'threshold_critical' \| 'limit_exceeded' \| 'anomaly_detected' \| 'projection_exceeded'>` | ✅ | | +| **severity** | `Enum<'info' \| 'warning' \| 'critical'>` | ✅ | | +| **budgetId** | `string` | optional | | +| **budgetType** | `Enum<'global' \| 'user' \| 'agent' \| 'object' \| 'project' \| 'department'>` | optional | | +| **scope** | `string` | optional | | +| **message** | `string` | ✅ | Alert message | +| **currentCost** | `number` | ✅ | | +| **maxCost** | `number` | optional | | +| **threshold** | `number` | optional | | +| **currency** | `string` | optional | | +| **recommendations** | `string[]` | optional | | +| **acknowledged** | `boolean` | optional | | +| **acknowledgedBy** | `string` | optional | | +| **acknowledgedAt** | `string` | optional | | +| **resolved** | `boolean` | optional | | +| **metadata** | `Record` | optional | | + +--- + +## CostAlertType + +### Allowed Values + +* `threshold_warning` +* `threshold_critical` +* `limit_exceeded` +* `anomaly_detected` +* `projection_exceeded` + +--- + +## CostAnalytics + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **periodStart** | `string` | ✅ | ISO 8601 timestamp | +| **periodEnd** | `string` | ✅ | ISO 8601 timestamp | +| **totalCost** | `number` | ✅ | | +| **totalRequests** | `integer` | ✅ | | +| **totalTokens** | `integer` | optional | | +| **currency** | `string` | optional | | +| **averageCostPerRequest** | `number` | ✅ | | +| **averageCostPerToken** | `number` | optional | | +| **averageRequestsPerDay** | `number` | ✅ | | +| **costTrend** | `Enum<'increasing' \| 'decreasing' \| 'stable'>` | optional | | +| **trendPercentage** | `number` | optional | % change vs previous period | +| **byModel** | `object[]` | optional | | +| **byProvider** | `object[]` | optional | | +| **byUser** | `object[]` | optional | | +| **byAgent** | `object[]` | optional | | +| **byOperation** | `object[]` | optional | | +| **byDate** | `object[]` | optional | | +| **topModels** | `object[]` | optional | | +| **topUsers** | `object[]` | optional | | +| **topAgents** | `object[]` | optional | | +| **tokensPerDollar** | `number` | optional | | +| **requestsPerDollar** | `number` | optional | | + +--- + +## CostBreakdownDimension + +### Allowed Values + +* `model` +* `provider` +* `user` +* `agent` +* `object` +* `operation` +* `date` +* `hour` +* `tag` + +--- + +## CostBreakdownEntry + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **dimension** | `Enum<'model' \| 'provider' \| 'user' \| 'agent' \| 'object' \| 'operation' \| 'date' \| 'hour' \| 'tag'>` | ✅ | | +| **value** | `string` | ✅ | Dimension value (e.g., model ID, user ID) | +| **totalCost** | `number` | ✅ | | +| **requestCount** | `integer` | ✅ | | +| **totalTokens** | `integer` | optional | | +| **percentageOfTotal** | `number` | ✅ | | +| **periodStart** | `string` | optional | | +| **periodEnd** | `string` | optional | | + +--- + +## CostEntry + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | ✅ | Unique cost entry ID | +| **timestamp** | `string` | ✅ | ISO 8601 timestamp | +| **modelId** | `string` | ✅ | AI model used | +| **provider** | `string` | ✅ | AI provider (e.g., "openai", "anthropic") | +| **operation** | `string` | ✅ | Operation type (e.g., "chat_completion", "embedding") | +| **promptTokens** | `integer` | optional | | +| **completionTokens** | `integer` | optional | | +| **totalTokens** | `integer` | optional | | +| **requestCount** | `integer` | optional | | +| **promptCost** | `number` | optional | Cost of prompt tokens | +| **completionCost** | `number` | optional | Cost of completion tokens | +| **totalCost** | `number` | ✅ | Total cost in base currency | +| **currency** | `string` | optional | | +| **sessionId** | `string` | optional | Conversation session ID | +| **userId** | `string` | optional | User who triggered the request | +| **agentId** | `string` | optional | AI agent ID | +| **object** | `string` | optional | Related object (e.g., "case", "project") | +| **recordId** | `string` | optional | Related record ID | +| **tags** | `string[]` | optional | | +| **metadata** | `Record` | optional | | + +--- + +## CostMetricType + +### Allowed Values + +* `token` +* `request` +* `character` +* `second` +* `image` +* `embedding` + +--- + +## CostOptimizationRecommendation + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | ✅ | | +| **type** | `Enum<'switch_model' \| 'reduce_tokens' \| 'batch_requests' \| 'cache_results' \| 'adjust_parameters' \| 'limit_usage'>` | ✅ | | +| **title** | `string` | ✅ | | +| **description** | `string` | ✅ | | +| **estimatedSavings** | `number` | optional | | +| **savingsPercentage** | `number` | optional | | +| **priority** | `Enum<'low' \| 'medium' \| 'high'>` | ✅ | | +| **effort** | `Enum<'low' \| 'medium' \| 'high'>` | ✅ | | +| **actionable** | `boolean` | optional | | +| **actionSteps** | `string[]` | optional | | +| **targetModel** | `string` | optional | | +| **alternativeModel** | `string` | optional | | +| **affectedUsers** | `string[]` | optional | | +| **status** | `Enum<'pending' \| 'accepted' \| 'rejected' \| 'implemented'>` | optional | | +| **implementedAt** | `string` | optional | | + +--- + +## CostQueryFilters + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **startDate** | `string` | optional | ISO 8601 timestamp | +| **endDate** | `string` | optional | ISO 8601 timestamp | +| **modelIds** | `string[]` | optional | | +| **providers** | `string[]` | optional | | +| **userIds** | `string[]` | optional | | +| **agentIds** | `string[]` | optional | | +| **operations** | `string[]` | optional | | +| **sessionIds** | `string[]` | optional | | +| **minCost** | `number` | optional | | +| **maxCost** | `number` | optional | | +| **tags** | `string[]` | optional | | +| **groupBy** | `Enum<'model' \| 'provider' \| 'user' \| 'agent' \| 'object' \| 'operation' \| 'date' \| 'hour' \| 'tag'>[]` | optional | | +| **orderBy** | `Enum<'timestamp' \| 'cost' \| 'tokens'>` | optional | | +| **orderDirection** | `Enum<'asc' \| 'desc'>` | optional | | +| **limit** | `integer` | optional | | +| **offset** | `integer` | optional | | + +--- + +## CostReport + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | ✅ | | +| **name** | `string` | ✅ | | +| **generatedAt** | `string` | ✅ | ISO 8601 timestamp | +| **periodStart** | `string` | ✅ | ISO 8601 timestamp | +| **periodEnd** | `string` | ✅ | ISO 8601 timestamp | +| **period** | `Enum<'hourly' \| 'daily' \| 'weekly' \| 'monthly' \| 'quarterly' \| 'yearly' \| 'custom'>` | ✅ | | +| **analytics** | `object` | ✅ | | +| **budgets** | `object[]` | optional | | +| **alerts** | `object[]` | optional | | +| **activeAlertCount** | `integer` | optional | | +| **recommendations** | `object[]` | optional | | +| **previousPeriodCost** | `number` | optional | | +| **costChange** | `number` | optional | Change vs previous period | +| **costChangePercentage** | `number` | optional | | +| **forecastedCost** | `number` | optional | | +| **forecastedBudgetStatus** | `Enum<'under' \| 'at' \| 'over'>` | optional | | +| **format** | `Enum<'summary' \| 'detailed' \| 'executive'>` | optional | | +| **currency** | `string` | optional | | + diff --git a/content/docs/references/ai/cost/BillingPeriod.mdx b/content/docs/references/ai/cost/BillingPeriod.mdx deleted file mode 100644 index 1baf034f5..000000000 --- a/content/docs/references/ai/cost/BillingPeriod.mdx +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: BillingPeriod -description: BillingPeriod Schema Reference ---- - -## Allowed Values - -* `hourly` -* `daily` -* `weekly` -* `monthly` -* `quarterly` -* `yearly` -* `custom` \ No newline at end of file diff --git a/content/docs/references/ai/cost/BudgetLimit.mdx b/content/docs/references/ai/cost/BudgetLimit.mdx deleted file mode 100644 index 4d21aaeec..000000000 --- a/content/docs/references/ai/cost/BudgetLimit.mdx +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: BudgetLimit -description: BudgetLimit Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `Enum<'global' \| 'user' \| 'agent' \| 'object' \| 'project' \| 'department'>` | ✅ | | -| **scope** | `string` | optional | Scope identifier (userId, agentId, etc.) | -| **maxCost** | `number` | ✅ | Maximum cost limit | -| **currency** | `string` | optional | | -| **period** | `Enum<'hourly' \| 'daily' \| 'weekly' \| 'monthly' \| 'quarterly' \| 'yearly' \| 'custom'>` | ✅ | | -| **customPeriodDays** | `integer` | optional | Custom period in days | -| **softLimit** | `number` | optional | Soft limit for warnings | -| **warnThresholds** | `number[]` | optional | Warning thresholds (e.g., [0.5, 0.8, 0.95]) | -| **enforced** | `boolean` | optional | Block requests when exceeded | -| **gracePeriodSeconds** | `integer` | optional | Grace period after limit exceeded | -| **allowRollover** | `boolean` | optional | Allow unused budget to rollover | -| **maxRolloverPercentage** | `number` | optional | Max rollover as % of limit | -| **name** | `string` | optional | Budget name | -| **description** | `string` | optional | | -| **active** | `boolean` | optional | | -| **tags** | `string[]` | optional | | diff --git a/content/docs/references/ai/cost/BudgetStatus.mdx b/content/docs/references/ai/cost/BudgetStatus.mdx deleted file mode 100644 index 4e1936779..000000000 --- a/content/docs/references/ai/cost/BudgetStatus.mdx +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: BudgetStatus -description: BudgetStatus Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **budgetId** | `string` | ✅ | | -| **type** | `Enum<'global' \| 'user' \| 'agent' \| 'object' \| 'project' \| 'department'>` | ✅ | | -| **scope** | `string` | optional | | -| **periodStart** | `string` | ✅ | ISO 8601 timestamp | -| **periodEnd** | `string` | ✅ | ISO 8601 timestamp | -| **currentCost** | `number` | optional | | -| **maxCost** | `number` | ✅ | | -| **currency** | `string` | optional | | -| **percentageUsed** | `number` | ✅ | Usage as percentage (can exceed 1.0 if over budget) | -| **remainingCost** | `number` | ✅ | Remaining budget (can be negative if exceeded) | -| **isExceeded** | `boolean` | optional | | -| **isWarning** | `boolean` | optional | | -| **projectedCost** | `number` | optional | Projected cost for period | -| **projectedOverage** | `number` | optional | Projected overage | -| **lastUpdated** | `string` | ✅ | ISO 8601 timestamp | diff --git a/content/docs/references/ai/cost/BudgetType.mdx b/content/docs/references/ai/cost/BudgetType.mdx deleted file mode 100644 index 6a73df905..000000000 --- a/content/docs/references/ai/cost/BudgetType.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: BudgetType -description: BudgetType Schema Reference ---- - -## Allowed Values - -* `global` -* `user` -* `agent` -* `object` -* `project` -* `department` \ No newline at end of file diff --git a/content/docs/references/ai/cost/CostAlert.mdx b/content/docs/references/ai/cost/CostAlert.mdx deleted file mode 100644 index 71839ae17..000000000 --- a/content/docs/references/ai/cost/CostAlert.mdx +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: CostAlert -description: CostAlert Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | | -| **timestamp** | `string` | ✅ | ISO 8601 timestamp | -| **type** | `Enum<'threshold_warning' \| 'threshold_critical' \| 'limit_exceeded' \| 'anomaly_detected' \| 'projection_exceeded'>` | ✅ | | -| **severity** | `Enum<'info' \| 'warning' \| 'critical'>` | ✅ | | -| **budgetId** | `string` | optional | | -| **budgetType** | `Enum<'global' \| 'user' \| 'agent' \| 'object' \| 'project' \| 'department'>` | optional | | -| **scope** | `string` | optional | | -| **message** | `string` | ✅ | Alert message | -| **currentCost** | `number` | ✅ | | -| **maxCost** | `number` | optional | | -| **threshold** | `number` | optional | | -| **currency** | `string` | optional | | -| **recommendations** | `string[]` | optional | | -| **acknowledged** | `boolean` | optional | | -| **acknowledgedBy** | `string` | optional | | -| **acknowledgedAt** | `string` | optional | | -| **resolved** | `boolean` | optional | | -| **metadata** | `Record` | optional | | diff --git a/content/docs/references/ai/cost/CostAlertType.mdx b/content/docs/references/ai/cost/CostAlertType.mdx deleted file mode 100644 index 1f086c20c..000000000 --- a/content/docs/references/ai/cost/CostAlertType.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: CostAlertType -description: CostAlertType Schema Reference ---- - -## Allowed Values - -* `threshold_warning` -* `threshold_critical` -* `limit_exceeded` -* `anomaly_detected` -* `projection_exceeded` \ No newline at end of file diff --git a/content/docs/references/ai/cost/CostAnalytics.mdx b/content/docs/references/ai/cost/CostAnalytics.mdx deleted file mode 100644 index 15f44483b..000000000 --- a/content/docs/references/ai/cost/CostAnalytics.mdx +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: CostAnalytics -description: CostAnalytics Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **periodStart** | `string` | ✅ | ISO 8601 timestamp | -| **periodEnd** | `string` | ✅ | ISO 8601 timestamp | -| **totalCost** | `number` | ✅ | | -| **totalRequests** | `integer` | ✅ | | -| **totalTokens** | `integer` | optional | | -| **currency** | `string` | optional | | -| **averageCostPerRequest** | `number` | ✅ | | -| **averageCostPerToken** | `number` | optional | | -| **averageRequestsPerDay** | `number` | ✅ | | -| **costTrend** | `Enum<'increasing' \| 'decreasing' \| 'stable'>` | optional | | -| **trendPercentage** | `number` | optional | % change vs previous period | -| **byModel** | `object[]` | optional | | -| **byProvider** | `object[]` | optional | | -| **byUser** | `object[]` | optional | | -| **byAgent** | `object[]` | optional | | -| **byOperation** | `object[]` | optional | | -| **byDate** | `object[]` | optional | | -| **topModels** | `object[]` | optional | | -| **topUsers** | `object[]` | optional | | -| **topAgents** | `object[]` | optional | | -| **tokensPerDollar** | `number` | optional | | -| **requestsPerDollar** | `number` | optional | | diff --git a/content/docs/references/ai/cost/CostBreakdownDimension.mdx b/content/docs/references/ai/cost/CostBreakdownDimension.mdx deleted file mode 100644 index f52054965..000000000 --- a/content/docs/references/ai/cost/CostBreakdownDimension.mdx +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: CostBreakdownDimension -description: CostBreakdownDimension Schema Reference ---- - -## Allowed Values - -* `model` -* `provider` -* `user` -* `agent` -* `object` -* `operation` -* `date` -* `hour` -* `tag` \ No newline at end of file diff --git a/content/docs/references/ai/cost/CostBreakdownEntry.mdx b/content/docs/references/ai/cost/CostBreakdownEntry.mdx deleted file mode 100644 index 9fd1c8ff3..000000000 --- a/content/docs/references/ai/cost/CostBreakdownEntry.mdx +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: CostBreakdownEntry -description: CostBreakdownEntry Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **dimension** | `Enum<'model' \| 'provider' \| 'user' \| 'agent' \| 'object' \| 'operation' \| 'date' \| 'hour' \| 'tag'>` | ✅ | | -| **value** | `string` | ✅ | Dimension value (e.g., model ID, user ID) | -| **totalCost** | `number` | ✅ | | -| **requestCount** | `integer` | ✅ | | -| **totalTokens** | `integer` | optional | | -| **percentageOfTotal** | `number` | ✅ | | -| **periodStart** | `string` | optional | | -| **periodEnd** | `string` | optional | | diff --git a/content/docs/references/ai/cost/CostEntry.mdx b/content/docs/references/ai/cost/CostEntry.mdx deleted file mode 100644 index 2be46d286..000000000 --- a/content/docs/references/ai/cost/CostEntry.mdx +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: CostEntry -description: CostEntry Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Unique cost entry ID | -| **timestamp** | `string` | ✅ | ISO 8601 timestamp | -| **modelId** | `string` | ✅ | AI model used | -| **provider** | `string` | ✅ | AI provider (e.g., "openai", "anthropic") | -| **operation** | `string` | ✅ | Operation type (e.g., "chat_completion", "embedding") | -| **promptTokens** | `integer` | optional | | -| **completionTokens** | `integer` | optional | | -| **totalTokens** | `integer` | optional | | -| **requestCount** | `integer` | optional | | -| **promptCost** | `number` | optional | Cost of prompt tokens | -| **completionCost** | `number` | optional | Cost of completion tokens | -| **totalCost** | `number` | ✅ | Total cost in base currency | -| **currency** | `string` | optional | | -| **sessionId** | `string` | optional | Conversation session ID | -| **userId** | `string` | optional | User who triggered the request | -| **agentId** | `string` | optional | AI agent ID | -| **object** | `string` | optional | Related object (e.g., "case", "project") | -| **recordId** | `string` | optional | Related record ID | -| **tags** | `string[]` | optional | | -| **metadata** | `Record` | optional | | diff --git a/content/docs/references/ai/cost/CostMetricType.mdx b/content/docs/references/ai/cost/CostMetricType.mdx deleted file mode 100644 index 29e70e3f0..000000000 --- a/content/docs/references/ai/cost/CostMetricType.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: CostMetricType -description: CostMetricType Schema Reference ---- - -## Allowed Values - -* `token` -* `request` -* `character` -* `second` -* `image` -* `embedding` \ No newline at end of file diff --git a/content/docs/references/ai/cost/CostOptimizationRecommendation.mdx b/content/docs/references/ai/cost/CostOptimizationRecommendation.mdx deleted file mode 100644 index a5a2ed947..000000000 --- a/content/docs/references/ai/cost/CostOptimizationRecommendation.mdx +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: CostOptimizationRecommendation -description: CostOptimizationRecommendation Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | | -| **type** | `Enum<'switch_model' \| 'reduce_tokens' \| 'batch_requests' \| 'cache_results' \| 'adjust_parameters' \| 'limit_usage'>` | ✅ | | -| **title** | `string` | ✅ | | -| **description** | `string` | ✅ | | -| **estimatedSavings** | `number` | optional | | -| **savingsPercentage** | `number` | optional | | -| **priority** | `Enum<'low' \| 'medium' \| 'high'>` | ✅ | | -| **effort** | `Enum<'low' \| 'medium' \| 'high'>` | ✅ | | -| **actionable** | `boolean` | optional | | -| **actionSteps** | `string[]` | optional | | -| **targetModel** | `string` | optional | | -| **alternativeModel** | `string` | optional | | -| **affectedUsers** | `string[]` | optional | | -| **status** | `Enum<'pending' \| 'accepted' \| 'rejected' \| 'implemented'>` | optional | | -| **implementedAt** | `string` | optional | | diff --git a/content/docs/references/ai/cost/CostQueryFilters.mdx b/content/docs/references/ai/cost/CostQueryFilters.mdx deleted file mode 100644 index 2824bc8a6..000000000 --- a/content/docs/references/ai/cost/CostQueryFilters.mdx +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: CostQueryFilters -description: CostQueryFilters Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **startDate** | `string` | optional | ISO 8601 timestamp | -| **endDate** | `string` | optional | ISO 8601 timestamp | -| **modelIds** | `string[]` | optional | | -| **providers** | `string[]` | optional | | -| **userIds** | `string[]` | optional | | -| **agentIds** | `string[]` | optional | | -| **operations** | `string[]` | optional | | -| **sessionIds** | `string[]` | optional | | -| **minCost** | `number` | optional | | -| **maxCost** | `number` | optional | | -| **tags** | `string[]` | optional | | -| **groupBy** | `Enum<'model' \| 'provider' \| 'user' \| 'agent' \| 'object' \| 'operation' \| 'date' \| 'hour' \| 'tag'>[]` | optional | | -| **orderBy** | `Enum<'timestamp' \| 'cost' \| 'tokens'>` | optional | | -| **orderDirection** | `Enum<'asc' \| 'desc'>` | optional | | -| **limit** | `integer` | optional | | -| **offset** | `integer` | optional | | diff --git a/content/docs/references/ai/cost/CostReport.mdx b/content/docs/references/ai/cost/CostReport.mdx deleted file mode 100644 index 556b504ae..000000000 --- a/content/docs/references/ai/cost/CostReport.mdx +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: CostReport -description: CostReport Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | | -| **name** | `string` | ✅ | | -| **generatedAt** | `string` | ✅ | ISO 8601 timestamp | -| **periodStart** | `string` | ✅ | ISO 8601 timestamp | -| **periodEnd** | `string` | ✅ | ISO 8601 timestamp | -| **period** | `Enum<'hourly' \| 'daily' \| 'weekly' \| 'monthly' \| 'quarterly' \| 'yearly' \| 'custom'>` | ✅ | | -| **analytics** | `object` | ✅ | | -| **budgets** | `object[]` | optional | | -| **alerts** | `object[]` | optional | | -| **activeAlertCount** | `integer` | optional | | -| **recommendations** | `object[]` | optional | | -| **previousPeriodCost** | `number` | optional | | -| **costChange** | `number` | optional | Change vs previous period | -| **costChangePercentage** | `number` | optional | | -| **forecastedCost** | `number` | optional | | -| **forecastedBudgetStatus** | `Enum<'under' \| 'at' \| 'over'>` | optional | | -| **format** | `Enum<'summary' \| 'detailed' \| 'executive'>` | optional | | -| **currency** | `string` | optional | | diff --git a/content/docs/references/ai/cost/meta.json b/content/docs/references/ai/cost/meta.json deleted file mode 100644 index e2969ca4b..000000000 --- a/content/docs/references/ai/cost/meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "title": "Cost" -} \ No newline at end of file diff --git a/content/docs/references/ai/index.mdx b/content/docs/references/ai/index.mdx new file mode 100644 index 000000000..e20102453 --- /dev/null +++ b/content/docs/references/ai/index.mdx @@ -0,0 +1,20 @@ +--- +title: AI Protocol Overview +description: Complete reference for all ai protocol schemas +--- + +# AI Protocol + +This section contains all protocol schemas for the ai layer of ObjectStack. + + + + + + + + + + + + diff --git a/content/docs/references/ai/model-registry.mdx b/content/docs/references/ai/model-registry.mdx new file mode 100644 index 000000000..4b7d2d2c8 --- /dev/null +++ b/content/docs/references/ai/model-registry.mdx @@ -0,0 +1,187 @@ +--- +title: Model Registry +description: Model Registry protocol schemas +--- + +# Model Registry + + +**Source:** `packages/spec/src/ai/model-registry.zod.ts` + + +## TypeScript Usage + +```typescript +import { ModelCapabilitySchema, ModelConfigSchema, ModelLimitsSchema, ModelPricingSchema, ModelProviderSchema, ModelRegistrySchema, ModelRegistryEntrySchema, ModelSelectionCriteriaSchema, PromptTemplateSchema, PromptVariableSchema } from '@objectstack/spec/ai'; +import type { ModelCapability, ModelConfig, ModelLimits, ModelPricing, ModelProvider, ModelRegistry, ModelRegistryEntry, ModelSelectionCriteria, PromptTemplate, PromptVariable } from '@objectstack/spec/ai'; + +// Validate data +const result = ModelCapabilitySchema.parse(data); +``` + +--- + +## ModelCapability + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **textGeneration** | `boolean` | optional | Supports text generation | +| **textEmbedding** | `boolean` | optional | Supports text embedding | +| **imageGeneration** | `boolean` | optional | Supports image generation | +| **imageUnderstanding** | `boolean` | optional | Supports image understanding | +| **functionCalling** | `boolean` | optional | Supports function calling | +| **codeGeneration** | `boolean` | optional | Supports code generation | +| **reasoning** | `boolean` | optional | Supports advanced reasoning | + +--- + +## ModelConfig + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | ✅ | Unique model identifier | +| **name** | `string` | ✅ | Model display name | +| **version** | `string` | ✅ | Model version (e.g., "gpt-4-turbo-2024-04-09") | +| **provider** | `Enum<'openai' \| 'azure_openai' \| 'anthropic' \| 'google' \| 'cohere' \| 'huggingface' \| 'local' \| 'custom'>` | ✅ | | +| **capabilities** | `object` | ✅ | | +| **limits** | `object` | ✅ | | +| **pricing** | `object` | optional | | +| **endpoint** | `string` | optional | Custom API endpoint | +| **apiKey** | `string` | optional | API key or reference to secret | +| **region** | `string` | optional | Deployment region (e.g., "us-east-1") | +| **description** | `string` | optional | | +| **tags** | `string[]` | optional | Tags for categorization | +| **deprecated** | `boolean` | optional | | +| **recommendedFor** | `string[]` | optional | Use case recommendations | + +--- + +## ModelLimits + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **maxTokens** | `integer` | ✅ | Maximum tokens per request | +| **contextWindow** | `integer` | ✅ | Context window size | +| **maxOutputTokens** | `integer` | optional | Maximum output tokens | +| **rateLimit** | `object` | optional | | + +--- + +## ModelPricing + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **currency** | `string` | optional | | +| **inputCostPer1kTokens** | `number` | optional | Cost per 1K input tokens | +| **outputCostPer1kTokens** | `number` | optional | Cost per 1K output tokens | +| **embeddingCostPer1kTokens** | `number` | optional | Cost per 1K embedding tokens | + +--- + +## ModelProvider + +### Allowed Values + +* `openai` +* `azure_openai` +* `anthropic` +* `google` +* `cohere` +* `huggingface` +* `local` +* `custom` + +--- + +## ModelRegistry + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Registry name | +| **models** | `Record` | ✅ | Model entries by ID | +| **promptTemplates** | `Record` | optional | Prompt templates by name | +| **defaultModel** | `string` | optional | Default model ID | +| **enableAutoFallback** | `boolean` | optional | Auto-fallback on errors | + +--- + +## ModelRegistryEntry + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **model** | `object` | ✅ | | +| **status** | `Enum<'active' \| 'deprecated' \| 'experimental' \| 'disabled'>` | optional | | +| **priority** | `integer` | optional | Priority for model selection | +| **fallbackModels** | `string[]` | optional | Fallback model IDs | +| **healthCheck** | `object` | optional | | + +--- + +## ModelSelectionCriteria + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **capabilities** | `string[]` | optional | Required capabilities | +| **maxCostPer1kTokens** | `number` | optional | Maximum acceptable cost | +| **minContextWindow** | `number` | optional | Minimum context window size | +| **provider** | `Enum<'openai' \| 'azure_openai' \| 'anthropic' \| 'google' \| 'cohere' \| 'huggingface' \| 'local' \| 'custom'>` | optional | | +| **tags** | `string[]` | optional | | +| **excludeDeprecated** | `boolean` | optional | | + +--- + +## PromptTemplate + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | ✅ | Unique template identifier | +| **name** | `string` | ✅ | Template name (snake_case) | +| **label** | `string` | ✅ | Display name | +| **system** | `string` | optional | System prompt | +| **user** | `string` | ✅ | User prompt template with variables | +| **assistant** | `string` | optional | Assistant message prefix | +| **variables** | `object[]` | optional | Template variables | +| **modelId** | `string` | optional | Recommended model ID | +| **temperature** | `number` | optional | | +| **maxTokens** | `number` | optional | | +| **topP** | `number` | optional | | +| **frequencyPenalty** | `number` | optional | | +| **presencePenalty** | `number` | optional | | +| **stopSequences** | `string[]` | optional | | +| **version** | `string` | optional | | +| **description** | `string` | optional | | +| **category** | `string` | optional | Template category (e.g., "code_generation", "support") | +| **tags** | `string[]` | optional | | +| **examples** | `object[]` | optional | | + +--- + +## PromptVariable + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Variable name (e.g., "user_name", "context") | +| **type** | `Enum<'string' \| 'number' \| 'boolean' \| 'object' \| 'array'>` | optional | | +| **required** | `boolean` | optional | | +| **defaultValue** | `any` | optional | | +| **description** | `string` | optional | | +| **validation** | `object` | optional | | + diff --git a/content/docs/references/ai/model-registry/ModelCapability.mdx b/content/docs/references/ai/model-registry/ModelCapability.mdx deleted file mode 100644 index 6773ec578..000000000 --- a/content/docs/references/ai/model-registry/ModelCapability.mdx +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: ModelCapability -description: ModelCapability Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **textGeneration** | `boolean` | optional | Supports text generation | -| **textEmbedding** | `boolean` | optional | Supports text embedding | -| **imageGeneration** | `boolean` | optional | Supports image generation | -| **imageUnderstanding** | `boolean` | optional | Supports image understanding | -| **functionCalling** | `boolean` | optional | Supports function calling | -| **codeGeneration** | `boolean` | optional | Supports code generation | -| **reasoning** | `boolean` | optional | Supports advanced reasoning | diff --git a/content/docs/references/ai/model-registry/ModelConfig.mdx b/content/docs/references/ai/model-registry/ModelConfig.mdx deleted file mode 100644 index 7785c0d9a..000000000 --- a/content/docs/references/ai/model-registry/ModelConfig.mdx +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: ModelConfig -description: ModelConfig Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Unique model identifier | -| **name** | `string` | ✅ | Model display name | -| **version** | `string` | ✅ | Model version (e.g., "gpt-4-turbo-2024-04-09") | -| **provider** | `Enum<'openai' \| 'azure_openai' \| 'anthropic' \| 'google' \| 'cohere' \| 'huggingface' \| 'local' \| 'custom'>` | ✅ | | -| **capabilities** | `object` | ✅ | | -| **limits** | `object` | ✅ | | -| **pricing** | `object` | optional | | -| **endpoint** | `string` | optional | Custom API endpoint | -| **apiKey** | `string` | optional | API key or reference to secret | -| **region** | `string` | optional | Deployment region (e.g., "us-east-1") | -| **description** | `string` | optional | | -| **tags** | `string[]` | optional | Tags for categorization | -| **deprecated** | `boolean` | optional | | -| **recommendedFor** | `string[]` | optional | Use case recommendations | diff --git a/content/docs/references/ai/model-registry/ModelLimits.mdx b/content/docs/references/ai/model-registry/ModelLimits.mdx deleted file mode 100644 index ca682a199..000000000 --- a/content/docs/references/ai/model-registry/ModelLimits.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: ModelLimits -description: ModelLimits Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **maxTokens** | `integer` | ✅ | Maximum tokens per request | -| **contextWindow** | `integer` | ✅ | Context window size | -| **maxOutputTokens** | `integer` | optional | Maximum output tokens | -| **rateLimit** | `object` | optional | | diff --git a/content/docs/references/ai/model-registry/ModelPricing.mdx b/content/docs/references/ai/model-registry/ModelPricing.mdx deleted file mode 100644 index d94a8288e..000000000 --- a/content/docs/references/ai/model-registry/ModelPricing.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: ModelPricing -description: ModelPricing Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **currency** | `string` | optional | | -| **inputCostPer1kTokens** | `number` | optional | Cost per 1K input tokens | -| **outputCostPer1kTokens** | `number` | optional | Cost per 1K output tokens | -| **embeddingCostPer1kTokens** | `number` | optional | Cost per 1K embedding tokens | diff --git a/content/docs/references/ai/model-registry/ModelProvider.mdx b/content/docs/references/ai/model-registry/ModelProvider.mdx deleted file mode 100644 index 3f98f0fd4..000000000 --- a/content/docs/references/ai/model-registry/ModelProvider.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: ModelProvider -description: ModelProvider Schema Reference ---- - -## Allowed Values - -* `openai` -* `azure_openai` -* `anthropic` -* `google` -* `cohere` -* `huggingface` -* `local` -* `custom` \ No newline at end of file diff --git a/content/docs/references/ai/model-registry/ModelRegistry.mdx b/content/docs/references/ai/model-registry/ModelRegistry.mdx deleted file mode 100644 index a389e1cc3..000000000 --- a/content/docs/references/ai/model-registry/ModelRegistry.mdx +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: ModelRegistry -description: ModelRegistry Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Registry name | -| **models** | `Record` | ✅ | Model entries by ID | -| **promptTemplates** | `Record` | optional | Prompt templates by name | -| **defaultModel** | `string` | optional | Default model ID | -| **enableAutoFallback** | `boolean` | optional | Auto-fallback on errors | diff --git a/content/docs/references/ai/model-registry/ModelRegistryEntry.mdx b/content/docs/references/ai/model-registry/ModelRegistryEntry.mdx deleted file mode 100644 index 6fe82e36b..000000000 --- a/content/docs/references/ai/model-registry/ModelRegistryEntry.mdx +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: ModelRegistryEntry -description: ModelRegistryEntry Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **model** | `object` | ✅ | | -| **status** | `Enum<'active' \| 'deprecated' \| 'experimental' \| 'disabled'>` | optional | | -| **priority** | `integer` | optional | Priority for model selection | -| **fallbackModels** | `string[]` | optional | Fallback model IDs | -| **healthCheck** | `object` | optional | | diff --git a/content/docs/references/ai/model-registry/ModelSelectionCriteria.mdx b/content/docs/references/ai/model-registry/ModelSelectionCriteria.mdx deleted file mode 100644 index c3ee7946c..000000000 --- a/content/docs/references/ai/model-registry/ModelSelectionCriteria.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: ModelSelectionCriteria -description: ModelSelectionCriteria Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **capabilities** | `string[]` | optional | Required capabilities | -| **maxCostPer1kTokens** | `number` | optional | Maximum acceptable cost | -| **minContextWindow** | `number` | optional | Minimum context window size | -| **provider** | `Enum<'openai' \| 'azure_openai' \| 'anthropic' \| 'google' \| 'cohere' \| 'huggingface' \| 'local' \| 'custom'>` | optional | | -| **tags** | `string[]` | optional | | -| **excludeDeprecated** | `boolean` | optional | | diff --git a/content/docs/references/ai/model-registry/PromptTemplate.mdx b/content/docs/references/ai/model-registry/PromptTemplate.mdx deleted file mode 100644 index 437bda43d..000000000 --- a/content/docs/references/ai/model-registry/PromptTemplate.mdx +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: PromptTemplate -description: PromptTemplate Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Unique template identifier | -| **name** | `string` | ✅ | Template name (snake_case) | -| **label** | `string` | ✅ | Display name | -| **system** | `string` | optional | System prompt | -| **user** | `string` | ✅ | User prompt template with variables | -| **assistant** | `string` | optional | Assistant message prefix | -| **variables** | `object[]` | optional | Template variables | -| **modelId** | `string` | optional | Recommended model ID | -| **temperature** | `number` | optional | | -| **maxTokens** | `number` | optional | | -| **topP** | `number` | optional | | -| **frequencyPenalty** | `number` | optional | | -| **presencePenalty** | `number` | optional | | -| **stopSequences** | `string[]` | optional | | -| **version** | `string` | optional | | -| **description** | `string` | optional | | -| **category** | `string` | optional | Template category (e.g., "code_generation", "support") | -| **tags** | `string[]` | optional | | -| **examples** | `object[]` | optional | | diff --git a/content/docs/references/ai/model-registry/PromptVariable.mdx b/content/docs/references/ai/model-registry/PromptVariable.mdx deleted file mode 100644 index 10b694014..000000000 --- a/content/docs/references/ai/model-registry/PromptVariable.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: PromptVariable -description: PromptVariable Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Variable name (e.g., "user_name", "context") | -| **type** | `Enum<'string' \| 'number' \| 'boolean' \| 'object' \| 'array'>` | optional | | -| **required** | `boolean` | optional | | -| **defaultValue** | `any` | optional | | -| **description** | `string` | optional | | -| **validation** | `object` | optional | | diff --git a/content/docs/references/ai/model-registry/meta.json b/content/docs/references/ai/model-registry/meta.json deleted file mode 100644 index 189c7565d..000000000 --- a/content/docs/references/ai/model-registry/meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "title": "Model Registry" -} \ No newline at end of file diff --git a/content/docs/references/ai/nlq.mdx b/content/docs/references/ai/nlq.mdx new file mode 100644 index 000000000..deff51c9a --- /dev/null +++ b/content/docs/references/ai/nlq.mdx @@ -0,0 +1,239 @@ +--- +title: Nlq +description: Nlq protocol schemas +--- + +# Nlq + + +**Source:** `packages/spec/src/ai/nlq.zod.ts` + + +## TypeScript Usage + +```typescript +import { EntitySchema, FieldSynonymConfigSchema, NLQAnalyticsSchema, NLQFieldMappingSchema, NLQModelConfigSchema, NLQParseResultSchema, NLQRequestSchema, NLQResponseSchema, NLQTrainingExampleSchema, QueryContextSchema, QueryIntentSchema, QueryTemplateSchema, TimeframeSchema } from '@objectstack/spec/ai'; +import type { Entity, FieldSynonymConfig, NLQAnalytics, NLQFieldMapping, NLQModelConfig, NLQParseResult, NLQRequest, NLQResponse, NLQTrainingExample, QueryContext, QueryIntent, QueryTemplate, Timeframe } from '@objectstack/spec/ai'; + +// Validate data +const result = EntitySchema.parse(data); +``` + +--- + +## Entity + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **type** | `Enum<'object' \| 'field' \| 'value' \| 'operator' \| 'function' \| 'timeframe'>` | ✅ | | +| **text** | `string` | ✅ | Original text from query | +| **value** | `any` | optional | Normalized value | +| **confidence** | `number` | ✅ | Confidence score | +| **span** | `any[]` | optional | Character span in query | + +--- + +## FieldSynonymConfig + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **object** | `string` | ✅ | Object name | +| **field** | `string` | ✅ | Field name | +| **synonyms** | `string[]` | ✅ | Natural language synonyms | +| **examples** | `string[]` | optional | Example queries using synonyms | + +--- + +## NLQAnalytics + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **totalQueries** | `integer` | ✅ | | +| **successfulQueries** | `integer` | ✅ | | +| **failedQueries** | `integer` | ✅ | | +| **averageConfidence** | `number` | ✅ | | +| **intentDistribution** | `Record` | ✅ | Count by intent type | +| **topQueries** | `object[]` | ✅ | | +| **averageParseTime** | `number` | ✅ | Average parse time in milliseconds | +| **averageExecutionTime** | `number` | optional | | +| **lowConfidenceQueries** | `object[]` | ✅ | | +| **startDate** | `string` | ✅ | ISO timestamp | +| **endDate** | `string` | ✅ | ISO timestamp | + +--- + +## NLQFieldMapping + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **naturalLanguage** | `string` | ✅ | NL field name (e.g., "customer name") | +| **objectField** | `string` | ✅ | Actual field name (e.g., "account.name") | +| **object** | `string` | ✅ | Object name | +| **field** | `string` | ✅ | Field name | +| **confidence** | `number` | ✅ | | + +--- + +## NLQModelConfig + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **modelId** | `string` | ✅ | Model from registry | +| **systemPrompt** | `string` | optional | System prompt override | +| **includeSchema** | `boolean` | optional | Include object schema in prompt | +| **includeExamples** | `boolean` | optional | Include examples in prompt | +| **enableIntentDetection** | `boolean` | optional | | +| **intentThreshold** | `number` | optional | | +| **enableEntityRecognition** | `boolean` | optional | | +| **entityRecognitionModel** | `string` | optional | | +| **enableFuzzyMatching** | `boolean` | optional | Fuzzy match field names | +| **fuzzyMatchThreshold** | `number` | optional | | +| **enableTimeframeDetection** | `boolean` | optional | | +| **defaultTimeframe** | `string` | optional | Default timeframe if not specified | +| **enableCaching** | `boolean` | optional | | +| **cacheTTL** | `integer` | optional | Cache TTL in seconds | + +--- + +## NLQParseResult + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **originalQuery** | `string` | ✅ | | +| **intent** | `Enum<'select' \| 'aggregate' \| 'filter' \| 'sort' \| 'compare' \| 'trend' \| 'insight' \| 'create' \| 'update' \| 'delete'>` | ✅ | | +| **intentConfidence** | `number` | ✅ | | +| **entities** | `object[]` | ✅ | | +| **targetObject** | `string` | optional | Primary object to query | +| **fields** | `object[]` | optional | | +| **timeframe** | `object` | optional | | +| **ast** | `any` | optional | Generated ObjectQL AST | +| **confidence** | `number` | ✅ | Overall confidence | +| **ambiguities** | `object[]` | optional | Detected ambiguities requiring clarification | +| **alternatives** | `object[]` | optional | | + +--- + +## NLQRequest + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **query** | `string` | ✅ | Natural language query | +| **context** | `object` | optional | | +| **includeAlternatives** | `boolean` | optional | Include alternative interpretations | +| **maxAlternatives** | `integer` | optional | | +| **minConfidence** | `number` | optional | Minimum confidence threshold | +| **executeQuery** | `boolean` | optional | Execute query and return results | +| **maxResults** | `integer` | optional | Maximum results to return | + +--- + +## NLQResponse + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **parseResult** | `object` | ✅ | | +| **results** | `Record[]` | optional | Query results | +| **totalCount** | `integer` | optional | | +| **executionTime** | `number` | optional | Execution time in milliseconds | +| **needsClarification** | `boolean` | ✅ | Whether query needs clarification | +| **suggestions** | `string[]` | optional | Query refinement suggestions | + +--- + +## NLQTrainingExample + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **query** | `string` | ✅ | Natural language query | +| **context** | `object` | optional | | +| **expectedIntent** | `Enum<'select' \| 'aggregate' \| 'filter' \| 'sort' \| 'compare' \| 'trend' \| 'insight' \| 'create' \| 'update' \| 'delete'>` | ✅ | | +| **expectedObject** | `string` | optional | | +| **expectedAST** | `any` | optional | Expected ObjectQL AST | +| **category** | `string` | optional | Example category | +| **tags** | `string[]` | optional | | +| **notes** | `string` | optional | | + +--- + +## QueryContext + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **userId** | `string` | optional | | +| **userRole** | `string` | optional | | +| **currentObject** | `string` | optional | Current object being viewed | +| **currentRecordId** | `string` | optional | Current record ID | +| **conversationHistory** | `object[]` | optional | | +| **defaultLimit** | `integer` | optional | | +| **timezone** | `string` | optional | | +| **locale** | `string` | optional | | + +--- + +## QueryIntent + +### Allowed Values + +* `select` +* `aggregate` +* `filter` +* `sort` +* `compare` +* `trend` +* `insight` +* `create` +* `update` +* `delete` + +--- + +## QueryTemplate + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | ✅ | | +| **name** | `string` | ✅ | Template name (snake_case) | +| **label** | `string` | ✅ | | +| **pattern** | `string` | ✅ | Query pattern with placeholders | +| **variables** | `object[]` | ✅ | | +| **astTemplate** | `any` | optional | AST template with variable placeholders | +| **category** | `string` | optional | | +| **examples** | `string[]` | optional | | +| **tags** | `string[]` | optional | | + +--- + +## Timeframe + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **type** | `Enum<'absolute' \| 'relative'>` | ✅ | | +| **start** | `string` | optional | Start date (ISO format) | +| **end** | `string` | optional | End date (ISO format) | +| **relative** | `object` | optional | | +| **text** | `string` | ✅ | Original timeframe text | + diff --git a/content/docs/references/ai/nlq/Entity.mdx b/content/docs/references/ai/nlq/Entity.mdx deleted file mode 100644 index 94de35e60..000000000 --- a/content/docs/references/ai/nlq/Entity.mdx +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: Entity -description: Entity Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `Enum<'object' \| 'field' \| 'value' \| 'operator' \| 'function' \| 'timeframe'>` | ✅ | | -| **text** | `string` | ✅ | Original text from query | -| **value** | `any` | optional | Normalized value | -| **confidence** | `number` | ✅ | Confidence score | -| **span** | `any[]` | optional | Character span in query | diff --git a/content/docs/references/ai/nlq/FieldSynonymConfig.mdx b/content/docs/references/ai/nlq/FieldSynonymConfig.mdx deleted file mode 100644 index a7f454f2d..000000000 --- a/content/docs/references/ai/nlq/FieldSynonymConfig.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: FieldSynonymConfig -description: FieldSynonymConfig Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **object** | `string` | ✅ | Object name | -| **field** | `string` | ✅ | Field name | -| **synonyms** | `string[]` | ✅ | Natural language synonyms | -| **examples** | `string[]` | optional | Example queries using synonyms | diff --git a/content/docs/references/ai/nlq/NLQAnalytics.mdx b/content/docs/references/ai/nlq/NLQAnalytics.mdx deleted file mode 100644 index f680f718e..000000000 --- a/content/docs/references/ai/nlq/NLQAnalytics.mdx +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: NLQAnalytics -description: NLQAnalytics Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **totalQueries** | `integer` | ✅ | | -| **successfulQueries** | `integer` | ✅ | | -| **failedQueries** | `integer` | ✅ | | -| **averageConfidence** | `number` | ✅ | | -| **intentDistribution** | `Record` | ✅ | Count by intent type | -| **topQueries** | `object[]` | ✅ | | -| **averageParseTime** | `number` | ✅ | Average parse time in milliseconds | -| **averageExecutionTime** | `number` | optional | | -| **lowConfidenceQueries** | `object[]` | ✅ | | -| **startDate** | `string` | ✅ | ISO timestamp | -| **endDate** | `string` | ✅ | ISO timestamp | diff --git a/content/docs/references/ai/nlq/NLQFieldMapping.mdx b/content/docs/references/ai/nlq/NLQFieldMapping.mdx deleted file mode 100644 index 872571d6e..000000000 --- a/content/docs/references/ai/nlq/NLQFieldMapping.mdx +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: NLQFieldMapping -description: NLQFieldMapping Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **naturalLanguage** | `string` | ✅ | NL field name (e.g., "customer name") | -| **objectField** | `string` | ✅ | Actual field name (e.g., "account.name") | -| **object** | `string` | ✅ | Object name | -| **field** | `string` | ✅ | Field name | -| **confidence** | `number` | ✅ | | diff --git a/content/docs/references/ai/nlq/NLQModelConfig.mdx b/content/docs/references/ai/nlq/NLQModelConfig.mdx deleted file mode 100644 index 00f845aa7..000000000 --- a/content/docs/references/ai/nlq/NLQModelConfig.mdx +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: NLQModelConfig -description: NLQModelConfig Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **modelId** | `string` | ✅ | Model from registry | -| **systemPrompt** | `string` | optional | System prompt override | -| **includeSchema** | `boolean` | optional | Include object schema in prompt | -| **includeExamples** | `boolean` | optional | Include examples in prompt | -| **enableIntentDetection** | `boolean` | optional | | -| **intentThreshold** | `number` | optional | | -| **enableEntityRecognition** | `boolean` | optional | | -| **entityRecognitionModel** | `string` | optional | | -| **enableFuzzyMatching** | `boolean` | optional | Fuzzy match field names | -| **fuzzyMatchThreshold** | `number` | optional | | -| **enableTimeframeDetection** | `boolean` | optional | | -| **defaultTimeframe** | `string` | optional | Default timeframe if not specified | -| **enableCaching** | `boolean` | optional | | -| **cacheTTL** | `integer` | optional | Cache TTL in seconds | diff --git a/content/docs/references/ai/nlq/NLQParseResult.mdx b/content/docs/references/ai/nlq/NLQParseResult.mdx deleted file mode 100644 index 9394bb6ce..000000000 --- a/content/docs/references/ai/nlq/NLQParseResult.mdx +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: NLQParseResult -description: NLQParseResult Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **originalQuery** | `string` | ✅ | | -| **intent** | `Enum<'select' \| 'aggregate' \| 'filter' \| 'sort' \| 'compare' \| 'trend' \| 'insight' \| 'create' \| 'update' \| 'delete'>` | ✅ | | -| **intentConfidence** | `number` | ✅ | | -| **entities** | `object[]` | ✅ | | -| **targetObject** | `string` | optional | Primary object to query | -| **fields** | `object[]` | optional | | -| **timeframe** | `object` | optional | | -| **ast** | `any` | optional | Generated ObjectQL AST | -| **confidence** | `number` | ✅ | Overall confidence | -| **ambiguities** | `object[]` | optional | Detected ambiguities requiring clarification | -| **alternatives** | `object[]` | optional | | diff --git a/content/docs/references/ai/nlq/NLQRequest.mdx b/content/docs/references/ai/nlq/NLQRequest.mdx deleted file mode 100644 index b19c9e38c..000000000 --- a/content/docs/references/ai/nlq/NLQRequest.mdx +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: NLQRequest -description: NLQRequest Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **query** | `string` | ✅ | Natural language query | -| **context** | `object` | optional | | -| **includeAlternatives** | `boolean` | optional | Include alternative interpretations | -| **maxAlternatives** | `integer` | optional | | -| **minConfidence** | `number` | optional | Minimum confidence threshold | -| **executeQuery** | `boolean` | optional | Execute query and return results | -| **maxResults** | `integer` | optional | Maximum results to return | diff --git a/content/docs/references/ai/nlq/NLQResponse.mdx b/content/docs/references/ai/nlq/NLQResponse.mdx deleted file mode 100644 index 1f95393a4..000000000 --- a/content/docs/references/ai/nlq/NLQResponse.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: NLQResponse -description: NLQResponse Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **parseResult** | `object` | ✅ | | -| **results** | `Record[]` | optional | Query results | -| **totalCount** | `integer` | optional | | -| **executionTime** | `number` | optional | Execution time in milliseconds | -| **needsClarification** | `boolean` | ✅ | Whether query needs clarification | -| **suggestions** | `string[]` | optional | Query refinement suggestions | diff --git a/content/docs/references/ai/nlq/NLQTrainingExample.mdx b/content/docs/references/ai/nlq/NLQTrainingExample.mdx deleted file mode 100644 index b1ed09435..000000000 --- a/content/docs/references/ai/nlq/NLQTrainingExample.mdx +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: NLQTrainingExample -description: NLQTrainingExample Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **query** | `string` | ✅ | Natural language query | -| **context** | `object` | optional | | -| **expectedIntent** | `Enum<'select' \| 'aggregate' \| 'filter' \| 'sort' \| 'compare' \| 'trend' \| 'insight' \| 'create' \| 'update' \| 'delete'>` | ✅ | | -| **expectedObject** | `string` | optional | | -| **expectedAST** | `any` | optional | Expected ObjectQL AST | -| **category** | `string` | optional | Example category | -| **tags** | `string[]` | optional | | -| **notes** | `string` | optional | | diff --git a/content/docs/references/ai/nlq/QueryContext.mdx b/content/docs/references/ai/nlq/QueryContext.mdx deleted file mode 100644 index 1651dda25..000000000 --- a/content/docs/references/ai/nlq/QueryContext.mdx +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: QueryContext -description: QueryContext Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **userId** | `string` | optional | | -| **userRole** | `string` | optional | | -| **currentObject** | `string` | optional | Current object being viewed | -| **currentRecordId** | `string` | optional | Current record ID | -| **conversationHistory** | `object[]` | optional | | -| **defaultLimit** | `integer` | optional | | -| **timezone** | `string` | optional | | -| **locale** | `string` | optional | | diff --git a/content/docs/references/ai/nlq/QueryIntent.mdx b/content/docs/references/ai/nlq/QueryIntent.mdx deleted file mode 100644 index 378c0a7c5..000000000 --- a/content/docs/references/ai/nlq/QueryIntent.mdx +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: QueryIntent -description: QueryIntent Schema Reference ---- - -## Allowed Values - -* `select` -* `aggregate` -* `filter` -* `sort` -* `compare` -* `trend` -* `insight` -* `create` -* `update` -* `delete` \ No newline at end of file diff --git a/content/docs/references/ai/nlq/QueryTemplate.mdx b/content/docs/references/ai/nlq/QueryTemplate.mdx deleted file mode 100644 index aac5d70c9..000000000 --- a/content/docs/references/ai/nlq/QueryTemplate.mdx +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: QueryTemplate -description: QueryTemplate Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | | -| **name** | `string` | ✅ | Template name (snake_case) | -| **label** | `string` | ✅ | | -| **pattern** | `string` | ✅ | Query pattern with placeholders | -| **variables** | `object[]` | ✅ | | -| **astTemplate** | `any` | optional | AST template with variable placeholders | -| **category** | `string` | optional | | -| **examples** | `string[]` | optional | | -| **tags** | `string[]` | optional | | diff --git a/content/docs/references/ai/nlq/Timeframe.mdx b/content/docs/references/ai/nlq/Timeframe.mdx deleted file mode 100644 index 5f6a0d8a4..000000000 --- a/content/docs/references/ai/nlq/Timeframe.mdx +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: Timeframe -description: Timeframe Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `Enum<'absolute' \| 'relative'>` | ✅ | | -| **start** | `string` | optional | Start date (ISO format) | -| **end** | `string` | optional | End date (ISO format) | -| **relative** | `object` | optional | | -| **text** | `string` | ✅ | Original timeframe text | diff --git a/content/docs/references/ai/nlq/meta.json b/content/docs/references/ai/nlq/meta.json deleted file mode 100644 index da4c491bf..000000000 --- a/content/docs/references/ai/nlq/meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "title": "Nlq" -} \ No newline at end of file diff --git a/content/docs/references/ai/orchestration.mdx b/content/docs/references/ai/orchestration.mdx new file mode 100644 index 000000000..bb0670c8f --- /dev/null +++ b/content/docs/references/ai/orchestration.mdx @@ -0,0 +1,189 @@ +--- +title: Orchestration +description: Orchestration protocol schemas +--- + +# Orchestration + + +**Source:** `packages/spec/src/ai/orchestration.zod.ts` + + +## TypeScript Usage + +```typescript +import { AIOrchestrationSchema, AIOrchestrationExecutionResultSchema, AIOrchestrationTriggerSchema, AITaskSchema, AITaskTypeSchema, BatchAIOrchestrationExecutionSchema, PostProcessingActionSchema, WorkflowFieldConditionSchema, WorkflowScheduleSchema } from '@objectstack/spec/ai'; +import type { AIOrchestration, AIOrchestrationExecutionResult, AIOrchestrationTrigger, AITask, AITaskType, BatchAIOrchestrationExecution, PostProcessingAction, WorkflowFieldCondition, WorkflowSchedule } from '@objectstack/spec/ai'; + +// Validate data +const result = AIOrchestrationSchema.parse(data); +``` + +--- + +## AIOrchestration + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Orchestration unique identifier (snake_case) | +| **label** | `string` | ✅ | Display name | +| **description** | `string` | optional | | +| **objectName** | `string` | ✅ | Target object for this orchestration | +| **trigger** | `Enum<'record_created' \| 'record_updated' \| 'field_changed' \| 'scheduled' \| 'manual' \| 'webhook' \| 'batch'>` | ✅ | | +| **fieldConditions** | `object[]` | optional | Fields to monitor (for field_changed trigger) | +| **schedule** | `object` | optional | Schedule configuration (for scheduled trigger) | +| **webhookConfig** | `object` | optional | Webhook configuration (for webhook trigger) | +| **entryCriteria** | `string` | optional | Formula condition - workflow only runs if TRUE | +| **aiTasks** | `object[]` | ✅ | AI tasks to execute in sequence | +| **postActions** | `object[]` | optional | Actions after AI tasks complete | +| **executionMode** | `Enum<'sequential' \| 'parallel'>` | optional | How to execute multiple AI tasks | +| **stopOnError** | `boolean` | optional | Stop workflow if any task fails | +| **timeout** | `number` | optional | Maximum execution time in seconds | +| **priority** | `Enum<'low' \| 'normal' \| 'high' \| 'critical'>` | optional | | +| **enableLogging** | `boolean` | optional | | +| **enableMetrics** | `boolean` | optional | | +| **notifyOnFailure** | `string[]` | optional | User IDs to notify on failure | +| **active** | `boolean` | optional | | +| **version** | `string` | optional | | +| **tags** | `string[]` | optional | | +| **category** | `string` | optional | Workflow category (e.g., "support", "sales", "hr") | +| **owner** | `string` | optional | User ID of workflow owner | +| **createdAt** | `string` | optional | ISO timestamp | +| **updatedAt** | `string` | optional | ISO timestamp | + +--- + +## AIOrchestrationExecutionResult + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **workflowName** | `string` | ✅ | | +| **recordId** | `string` | ✅ | | +| **status** | `Enum<'success' \| 'partial_success' \| 'failed' \| 'skipped'>` | ✅ | | +| **executionTime** | `number` | ✅ | Execution time in milliseconds | +| **tasksExecuted** | `integer` | ✅ | Number of tasks executed | +| **tasksSucceeded** | `integer` | ✅ | Number of tasks succeeded | +| **tasksFailed** | `integer` | ✅ | Number of tasks failed | +| **taskResults** | `object[]` | optional | | +| **error** | `string` | optional | | +| **startedAt** | `string` | ✅ | ISO timestamp | +| **completedAt** | `string` | optional | ISO timestamp | + +--- + +## AIOrchestrationTrigger + +### Allowed Values + +* `record_created` +* `record_updated` +* `field_changed` +* `scheduled` +* `manual` +* `webhook` +* `batch` + +--- + +## AITask + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | optional | Optional task ID for referencing | +| **name** | `string` | ✅ | Human-readable task name | +| **type** | `Enum<'classify' \| 'extract' \| 'summarize' \| 'generate' \| 'predict' \| 'translate' \| 'sentiment' \| 'entity_recognition' \| 'anomaly_detection' \| 'recommendation'>` | ✅ | | +| **model** | `string` | optional | Model ID from registry (uses default if not specified) | +| **promptTemplate** | `string` | optional | Prompt template ID for this task | +| **inputFields** | `string[]` | ✅ | Source fields to process (e.g., ["description", "comments"]) | +| **inputContext** | `Record` | optional | Additional context for the AI model | +| **outputField** | `string` | ✅ | Target field to store the result | +| **outputFormat** | `Enum<'text' \| 'json' \| 'number' \| 'boolean' \| 'array'>` | optional | | +| **classes** | `string[]` | optional | Valid classes for classification tasks | +| **multiClass** | `boolean` | optional | Allow multiple classes to be selected | +| **extractionSchema** | `Record` | optional | JSON schema for structured extraction | +| **maxLength** | `number` | optional | Maximum length for generated content | +| **temperature** | `number` | optional | Model temperature override | +| **fallbackValue** | `any` | optional | Fallback value if AI task fails | +| **retryAttempts** | `integer` | optional | | +| **condition** | `string` | optional | Formula condition - task only runs if TRUE | +| **description** | `string` | optional | | +| **active** | `boolean` | optional | | + +--- + +## AITaskType + +### Allowed Values + +* `classify` +* `extract` +* `summarize` +* `generate` +* `predict` +* `translate` +* `sentiment` +* `entity_recognition` +* `anomaly_detection` +* `recommendation` + +--- + +## BatchAIOrchestrationExecution + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **workflowName** | `string` | ✅ | Orchestration to execute | +| **recordIds** | `string[]` | ✅ | Records to process | +| **batchSize** | `integer` | optional | | +| **parallelism** | `integer` | optional | | +| **priority** | `Enum<'low' \| 'normal' \| 'high'>` | optional | | + +--- + +## PostProcessingAction + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **type** | `Enum<'field_update' \| 'send_email' \| 'create_record' \| 'update_related' \| 'trigger_flow' \| 'webhook'>` | ✅ | | +| **name** | `string` | ✅ | Action name | +| **config** | `Record` | ✅ | Action-specific configuration | +| **condition** | `string` | optional | Execute only if condition is TRUE | + +--- + +## WorkflowFieldCondition + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **field** | `string` | ✅ | Field name to monitor | +| **operator** | `Enum<'changed' \| 'changed_to' \| 'changed_from' \| 'is' \| 'is_not'>` | optional | | +| **value** | `any` | optional | Value to compare against (for changed_to/changed_from/is/is_not) | + +--- + +## WorkflowSchedule + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **type** | `Enum<'cron' \| 'interval' \| 'daily' \| 'weekly' \| 'monthly'>` | optional | | +| **cron** | `string` | optional | Cron expression (required if type is "cron") | +| **interval** | `number` | optional | Interval in minutes (required if type is "interval") | +| **time** | `string` | optional | Time of day for daily schedules (HH:MM format) | +| **dayOfWeek** | `integer` | optional | Day of week for weekly (0=Sunday) | +| **dayOfMonth** | `integer` | optional | Day of month for monthly | +| **timezone** | `string` | optional | | + diff --git a/content/docs/references/ai/orchestration/AIOrchestration.mdx b/content/docs/references/ai/orchestration/AIOrchestration.mdx deleted file mode 100644 index 75233ab94..000000000 --- a/content/docs/references/ai/orchestration/AIOrchestration.mdx +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: AIOrchestration -description: AIOrchestration Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Orchestration unique identifier (snake_case) | -| **label** | `string` | ✅ | Display name | -| **description** | `string` | optional | | -| **objectName** | `string` | ✅ | Target object for this orchestration | -| **trigger** | `Enum<'record_created' \| 'record_updated' \| 'field_changed' \| 'scheduled' \| 'manual' \| 'webhook' \| 'batch'>` | ✅ | | -| **fieldConditions** | `object[]` | optional | Fields to monitor (for field_changed trigger) | -| **schedule** | `object` | optional | Schedule configuration (for scheduled trigger) | -| **webhookConfig** | `object` | optional | Webhook configuration (for webhook trigger) | -| **entryCriteria** | `string` | optional | Formula condition - workflow only runs if TRUE | -| **aiTasks** | `object[]` | ✅ | AI tasks to execute in sequence | -| **postActions** | `object[]` | optional | Actions after AI tasks complete | -| **executionMode** | `Enum<'sequential' \| 'parallel'>` | optional | How to execute multiple AI tasks | -| **stopOnError** | `boolean` | optional | Stop workflow if any task fails | -| **timeout** | `number` | optional | Maximum execution time in seconds | -| **priority** | `Enum<'low' \| 'normal' \| 'high' \| 'critical'>` | optional | | -| **enableLogging** | `boolean` | optional | | -| **enableMetrics** | `boolean` | optional | | -| **notifyOnFailure** | `string[]` | optional | User IDs to notify on failure | -| **active** | `boolean` | optional | | -| **version** | `string` | optional | | -| **tags** | `string[]` | optional | | -| **category** | `string` | optional | Workflow category (e.g., "support", "sales", "hr") | -| **owner** | `string` | optional | User ID of workflow owner | -| **createdAt** | `string` | optional | ISO timestamp | -| **updatedAt** | `string` | optional | ISO timestamp | diff --git a/content/docs/references/ai/orchestration/AIOrchestrationExecutionResult.mdx b/content/docs/references/ai/orchestration/AIOrchestrationExecutionResult.mdx deleted file mode 100644 index 865b13f36..000000000 --- a/content/docs/references/ai/orchestration/AIOrchestrationExecutionResult.mdx +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: AIOrchestrationExecutionResult -description: AIOrchestrationExecutionResult Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **workflowName** | `string` | ✅ | | -| **recordId** | `string` | ✅ | | -| **status** | `Enum<'success' \| 'partial_success' \| 'failed' \| 'skipped'>` | ✅ | | -| **executionTime** | `number` | ✅ | Execution time in milliseconds | -| **tasksExecuted** | `integer` | ✅ | Number of tasks executed | -| **tasksSucceeded** | `integer` | ✅ | Number of tasks succeeded | -| **tasksFailed** | `integer` | ✅ | Number of tasks failed | -| **taskResults** | `object[]` | optional | | -| **error** | `string` | optional | | -| **startedAt** | `string` | ✅ | ISO timestamp | -| **completedAt** | `string` | optional | ISO timestamp | diff --git a/content/docs/references/ai/orchestration/AIOrchestrationTrigger.mdx b/content/docs/references/ai/orchestration/AIOrchestrationTrigger.mdx deleted file mode 100644 index 3ff9d846e..000000000 --- a/content/docs/references/ai/orchestration/AIOrchestrationTrigger.mdx +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: AIOrchestrationTrigger -description: AIOrchestrationTrigger Schema Reference ---- - -## Allowed Values - -* `record_created` -* `record_updated` -* `field_changed` -* `scheduled` -* `manual` -* `webhook` -* `batch` \ No newline at end of file diff --git a/content/docs/references/ai/orchestration/AITask.mdx b/content/docs/references/ai/orchestration/AITask.mdx deleted file mode 100644 index 0911f29b2..000000000 --- a/content/docs/references/ai/orchestration/AITask.mdx +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: AITask -description: AITask Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | optional | Optional task ID for referencing | -| **name** | `string` | ✅ | Human-readable task name | -| **type** | `Enum<'classify' \| 'extract' \| 'summarize' \| 'generate' \| 'predict' \| 'translate' \| 'sentiment' \| 'entity_recognition' \| 'anomaly_detection' \| 'recommendation'>` | ✅ | | -| **model** | `string` | optional | Model ID from registry (uses default if not specified) | -| **promptTemplate** | `string` | optional | Prompt template ID for this task | -| **inputFields** | `string[]` | ✅ | Source fields to process (e.g., ["description", "comments"]) | -| **inputContext** | `Record` | optional | Additional context for the AI model | -| **outputField** | `string` | ✅ | Target field to store the result | -| **outputFormat** | `Enum<'text' \| 'json' \| 'number' \| 'boolean' \| 'array'>` | optional | | -| **classes** | `string[]` | optional | Valid classes for classification tasks | -| **multiClass** | `boolean` | optional | Allow multiple classes to be selected | -| **extractionSchema** | `Record` | optional | JSON schema for structured extraction | -| **maxLength** | `number` | optional | Maximum length for generated content | -| **temperature** | `number` | optional | Model temperature override | -| **fallbackValue** | `any` | optional | Fallback value if AI task fails | -| **retryAttempts** | `integer` | optional | | -| **condition** | `string` | optional | Formula condition - task only runs if TRUE | -| **description** | `string` | optional | | -| **active** | `boolean` | optional | | diff --git a/content/docs/references/ai/orchestration/AITaskType.mdx b/content/docs/references/ai/orchestration/AITaskType.mdx deleted file mode 100644 index 5bc85239d..000000000 --- a/content/docs/references/ai/orchestration/AITaskType.mdx +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: AITaskType -description: AITaskType Schema Reference ---- - -## Allowed Values - -* `classify` -* `extract` -* `summarize` -* `generate` -* `predict` -* `translate` -* `sentiment` -* `entity_recognition` -* `anomaly_detection` -* `recommendation` \ No newline at end of file diff --git a/content/docs/references/ai/orchestration/BatchAIOrchestrationExecution.mdx b/content/docs/references/ai/orchestration/BatchAIOrchestrationExecution.mdx deleted file mode 100644 index bae06a30f..000000000 --- a/content/docs/references/ai/orchestration/BatchAIOrchestrationExecution.mdx +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: BatchAIOrchestrationExecution -description: BatchAIOrchestrationExecution Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **workflowName** | `string` | ✅ | Orchestration to execute | -| **recordIds** | `string[]` | ✅ | Records to process | -| **batchSize** | `integer` | optional | | -| **parallelism** | `integer` | optional | | -| **priority** | `Enum<'low' \| 'normal' \| 'high'>` | optional | | diff --git a/content/docs/references/ai/orchestration/PostProcessingAction.mdx b/content/docs/references/ai/orchestration/PostProcessingAction.mdx deleted file mode 100644 index a8c93ca76..000000000 --- a/content/docs/references/ai/orchestration/PostProcessingAction.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: PostProcessingAction -description: PostProcessingAction Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `Enum<'field_update' \| 'send_email' \| 'create_record' \| 'update_related' \| 'trigger_flow' \| 'webhook'>` | ✅ | | -| **name** | `string` | ✅ | Action name | -| **config** | `Record` | ✅ | Action-specific configuration | -| **condition** | `string` | optional | Execute only if condition is TRUE | diff --git a/content/docs/references/ai/orchestration/WorkflowFieldCondition.mdx b/content/docs/references/ai/orchestration/WorkflowFieldCondition.mdx deleted file mode 100644 index c5044e30e..000000000 --- a/content/docs/references/ai/orchestration/WorkflowFieldCondition.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: WorkflowFieldCondition -description: WorkflowFieldCondition Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **field** | `string` | ✅ | Field name to monitor | -| **operator** | `Enum<'changed' \| 'changed_to' \| 'changed_from' \| 'is' \| 'is_not'>` | optional | | -| **value** | `any` | optional | Value to compare against (for changed_to/changed_from/is/is_not) | diff --git a/content/docs/references/ai/orchestration/WorkflowSchedule.mdx b/content/docs/references/ai/orchestration/WorkflowSchedule.mdx deleted file mode 100644 index add93497f..000000000 --- a/content/docs/references/ai/orchestration/WorkflowSchedule.mdx +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: WorkflowSchedule -description: WorkflowSchedule Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `Enum<'cron' \| 'interval' \| 'daily' \| 'weekly' \| 'monthly'>` | optional | | -| **cron** | `string` | optional | Cron expression (required if type is "cron") | -| **interval** | `number` | optional | Interval in minutes (required if type is "interval") | -| **time** | `string` | optional | Time of day for daily schedules (HH:MM format) | -| **dayOfWeek** | `integer` | optional | Day of week for weekly (0=Sunday) | -| **dayOfMonth** | `integer` | optional | Day of month for monthly | -| **timezone** | `string` | optional | | diff --git a/content/docs/references/ai/orchestration/meta.json b/content/docs/references/ai/orchestration/meta.json deleted file mode 100644 index 76144ea5b..000000000 --- a/content/docs/references/ai/orchestration/meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "title": "Orchestration" -} \ No newline at end of file diff --git a/content/docs/references/ai/predictive.mdx b/content/docs/references/ai/predictive.mdx new file mode 100644 index 000000000..63e6eefe4 --- /dev/null +++ b/content/docs/references/ai/predictive.mdx @@ -0,0 +1,212 @@ +--- +title: Predictive +description: Predictive protocol schemas +--- + +# Predictive + + +**Source:** `packages/spec/src/ai/predictive.zod.ts` + + +## TypeScript Usage + +```typescript +import { EvaluationMetricsSchema, HyperparametersSchema, ModelDriftSchema, ModelFeatureSchema, PredictionRequestSchema, PredictionResultSchema, PredictiveModelSchema, PredictiveModelTypeSchema, TrainingConfigSchema } from '@objectstack/spec/ai'; +import type { EvaluationMetrics, Hyperparameters, ModelDrift, ModelFeature, PredictionRequest, PredictionResult, PredictiveModel, PredictiveModelType, TrainingConfig } from '@objectstack/spec/ai'; + +// Validate data +const result = EvaluationMetricsSchema.parse(data); +``` + +--- + +## EvaluationMetrics + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **accuracy** | `number` | optional | | +| **precision** | `number` | optional | | +| **recall** | `number` | optional | | +| **f1Score** | `number` | optional | | +| **auc** | `number` | optional | Area Under ROC Curve | +| **mse** | `number` | optional | Mean Squared Error | +| **rmse** | `number` | optional | Root Mean Squared Error | +| **mae** | `number` | optional | Mean Absolute Error | +| **r2Score** | `number` | optional | R-squared score | +| **silhouetteScore** | `number` | optional | | +| **daviesBouldinIndex** | `number` | optional | | +| **mape** | `number` | optional | Mean Absolute Percentage Error | +| **smape** | `number` | optional | Symmetric MAPE | +| **custom** | `Record` | optional | | + +--- + +## Hyperparameters + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **learningRate** | `number` | optional | Learning rate for training | +| **epochs** | `integer` | optional | Number of training epochs | +| **batchSize** | `integer` | optional | Training batch size | +| **maxDepth** | `integer` | optional | Maximum tree depth | +| **numTrees** | `integer` | optional | Number of trees in ensemble | +| **minSamplesSplit** | `integer` | optional | Minimum samples to split node | +| **minSamplesLeaf** | `integer` | optional | Minimum samples in leaf node | +| **hiddenLayers** | `integer[]` | optional | Hidden layer sizes | +| **activation** | `string` | optional | Activation function | +| **dropout** | `number` | optional | Dropout rate | +| **l1Regularization** | `number` | optional | L1 regularization strength | +| **l2Regularization** | `number` | optional | L2 regularization strength | +| **numClusters** | `integer` | optional | Number of clusters (k-means, etc.) | +| **seasonalPeriod** | `integer` | optional | Seasonal period for time series | +| **forecastHorizon** | `integer` | optional | Number of periods to forecast | +| **custom** | `Record` | optional | Algorithm-specific parameters | + +--- + +## ModelDrift + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **modelName** | `string` | ✅ | | +| **driftType** | `Enum<'feature_drift' \| 'prediction_drift' \| 'performance_drift'>` | ✅ | | +| **severity** | `Enum<'low' \| 'medium' \| 'high' \| 'critical'>` | ✅ | | +| **detectedAt** | `string` | ✅ | ISO timestamp | +| **metrics** | `object` | ✅ | | +| **recommendation** | `string` | optional | | +| **autoRetrainTriggered** | `boolean` | optional | | + +--- + +## ModelFeature + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Feature name (snake_case) | +| **label** | `string` | optional | Human-readable label | +| **field** | `string` | ✅ | Source field name | +| **object** | `string` | optional | Source object (if different from target) | +| **dataType** | `Enum<'numeric' \| 'categorical' \| 'text' \| 'datetime' \| 'boolean'>` | ✅ | Feature data type | +| **transformation** | `Enum<'none' \| 'normalize' \| 'standardize' \| 'one_hot_encode' \| 'label_encode' \| 'log_transform' \| 'binning' \| 'embedding'>` | optional | | +| **required** | `boolean` | optional | | +| **defaultValue** | `any` | optional | | +| **description** | `string` | optional | | +| **importance** | `number` | optional | Feature importance score (0-1) | + +--- + +## PredictionRequest + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **modelName** | `string` | ✅ | Model to use for prediction | +| **recordIds** | `string[]` | optional | Specific records to predict (if not provided, uses all) | +| **inputData** | `Record` | optional | Direct input data (alternative to recordIds) | +| **returnConfidence** | `boolean` | optional | | +| **returnExplanation** | `boolean` | optional | | + +--- + +## PredictionResult + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **modelName** | `string` | ✅ | | +| **modelVersion** | `string` | ✅ | | +| **recordId** | `string` | optional | | +| **prediction** | `any` | optional | The predicted value | +| **confidence** | `number` | optional | Confidence score (0-1) | +| **probabilities** | `Record` | optional | Class probabilities (for classification) | +| **explanation** | `object` | optional | | +| **metadata** | `object` | optional | | + +--- + +## PredictiveModel + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Model unique identifier (snake_case) | +| **label** | `string` | ✅ | Model display name | +| **description** | `string` | optional | | +| **type** | `Enum<'classification' \| 'regression' \| 'clustering' \| 'forecasting' \| 'anomaly_detection' \| 'recommendation' \| 'ranking'>` | ✅ | | +| **algorithm** | `string` | optional | Specific algorithm (e.g., "random_forest", "xgboost", "lstm") | +| **objectName** | `string` | ✅ | Target object for predictions | +| **target** | `string` | ✅ | Target field to predict | +| **targetType** | `Enum<'numeric' \| 'categorical' \| 'binary'>` | optional | Target field type | +| **features** | `object[]` | ✅ | Input features for the model | +| **hyperparameters** | `object` | optional | | +| **training** | `object` | optional | | +| **metrics** | `object` | optional | Evaluation metrics from last training | +| **deploymentStatus** | `Enum<'draft' \| 'training' \| 'trained' \| 'deployed' \| 'deprecated'>` | optional | | +| **version** | `string` | optional | | +| **predictionField** | `string` | optional | Field to store predictions | +| **confidenceField** | `string` | optional | Field to store confidence scores | +| **updateTrigger** | `Enum<'on_create' \| 'on_update' \| 'manual' \| 'scheduled'>` | optional | | +| **autoRetrain** | `boolean` | optional | | +| **retrainSchedule** | `string` | optional | Cron expression for auto-retraining | +| **retrainThreshold** | `number` | optional | Performance threshold to trigger retraining | +| **enableExplainability** | `boolean` | optional | Generate feature importance & explanations | +| **enableMonitoring** | `boolean` | optional | | +| **alertOnDrift** | `boolean` | optional | Alert when model drift is detected | +| **active** | `boolean` | optional | | +| **owner** | `string` | optional | User ID of model owner | +| **permissions** | `string[]` | optional | User/group IDs with access | +| **tags** | `string[]` | optional | | +| **category** | `string` | optional | Model category (e.g., "sales", "marketing", "operations") | +| **lastTrainedAt** | `string` | optional | ISO timestamp | +| **createdAt** | `string` | optional | ISO timestamp | +| **updatedAt** | `string` | optional | ISO timestamp | + +--- + +## PredictiveModelType + +### Allowed Values + +* `classification` +* `regression` +* `clustering` +* `forecasting` +* `anomaly_detection` +* `recommendation` +* `ranking` + +--- + +## TrainingConfig + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **trainingDataRatio** | `number` | optional | Proportion of data for training | +| **validationDataRatio** | `number` | optional | Proportion for validation | +| **testDataRatio** | `number` | optional | Proportion for testing | +| **dataFilter** | `string` | optional | Formula to filter training data | +| **minRecords** | `integer` | optional | Minimum records required | +| **maxRecords** | `integer` | optional | Maximum records to use | +| **strategy** | `Enum<'full' \| 'incremental' \| 'online' \| 'transfer_learning'>` | optional | | +| **crossValidation** | `boolean` | optional | | +| **folds** | `integer` | optional | Cross-validation folds | +| **earlyStoppingEnabled** | `boolean` | optional | | +| **earlyStoppingPatience** | `integer` | optional | Epochs without improvement before stopping | +| **maxTrainingTime** | `number` | optional | Maximum training time in seconds | +| **gpuEnabled** | `boolean` | optional | | +| **randomSeed** | `integer` | optional | Random seed for reproducibility | + diff --git a/content/docs/references/ai/predictive/EvaluationMetrics.mdx b/content/docs/references/ai/predictive/EvaluationMetrics.mdx deleted file mode 100644 index a41fda405..000000000 --- a/content/docs/references/ai/predictive/EvaluationMetrics.mdx +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: EvaluationMetrics -description: EvaluationMetrics Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **accuracy** | `number` | optional | | -| **precision** | `number` | optional | | -| **recall** | `number` | optional | | -| **f1Score** | `number` | optional | | -| **auc** | `number` | optional | Area Under ROC Curve | -| **mse** | `number` | optional | Mean Squared Error | -| **rmse** | `number` | optional | Root Mean Squared Error | -| **mae** | `number` | optional | Mean Absolute Error | -| **r2Score** | `number` | optional | R-squared score | -| **silhouetteScore** | `number` | optional | | -| **daviesBouldinIndex** | `number` | optional | | -| **mape** | `number` | optional | Mean Absolute Percentage Error | -| **smape** | `number` | optional | Symmetric MAPE | -| **custom** | `Record` | optional | | diff --git a/content/docs/references/ai/predictive/Hyperparameters.mdx b/content/docs/references/ai/predictive/Hyperparameters.mdx deleted file mode 100644 index 41f8e9d76..000000000 --- a/content/docs/references/ai/predictive/Hyperparameters.mdx +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: Hyperparameters -description: Hyperparameters Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **learningRate** | `number` | optional | Learning rate for training | -| **epochs** | `integer` | optional | Number of training epochs | -| **batchSize** | `integer` | optional | Training batch size | -| **maxDepth** | `integer` | optional | Maximum tree depth | -| **numTrees** | `integer` | optional | Number of trees in ensemble | -| **minSamplesSplit** | `integer` | optional | Minimum samples to split node | -| **minSamplesLeaf** | `integer` | optional | Minimum samples in leaf node | -| **hiddenLayers** | `integer[]` | optional | Hidden layer sizes | -| **activation** | `string` | optional | Activation function | -| **dropout** | `number` | optional | Dropout rate | -| **l1Regularization** | `number` | optional | L1 regularization strength | -| **l2Regularization** | `number` | optional | L2 regularization strength | -| **numClusters** | `integer` | optional | Number of clusters (k-means, etc.) | -| **seasonalPeriod** | `integer` | optional | Seasonal period for time series | -| **forecastHorizon** | `integer` | optional | Number of periods to forecast | -| **custom** | `Record` | optional | Algorithm-specific parameters | diff --git a/content/docs/references/ai/predictive/ModelDrift.mdx b/content/docs/references/ai/predictive/ModelDrift.mdx deleted file mode 100644 index 703e71bff..000000000 --- a/content/docs/references/ai/predictive/ModelDrift.mdx +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: ModelDrift -description: ModelDrift Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **modelName** | `string` | ✅ | | -| **driftType** | `Enum<'feature_drift' \| 'prediction_drift' \| 'performance_drift'>` | ✅ | | -| **severity** | `Enum<'low' \| 'medium' \| 'high' \| 'critical'>` | ✅ | | -| **detectedAt** | `string` | ✅ | ISO timestamp | -| **metrics** | `object` | ✅ | | -| **recommendation** | `string` | optional | | -| **autoRetrainTriggered** | `boolean` | optional | | diff --git a/content/docs/references/ai/predictive/ModelFeature.mdx b/content/docs/references/ai/predictive/ModelFeature.mdx deleted file mode 100644 index 992f21dae..000000000 --- a/content/docs/references/ai/predictive/ModelFeature.mdx +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: ModelFeature -description: ModelFeature Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Feature name (snake_case) | -| **label** | `string` | optional | Human-readable label | -| **field** | `string` | ✅ | Source field name | -| **object** | `string` | optional | Source object (if different from target) | -| **dataType** | `Enum<'numeric' \| 'categorical' \| 'text' \| 'datetime' \| 'boolean'>` | ✅ | Feature data type | -| **transformation** | `Enum<'none' \| 'normalize' \| 'standardize' \| 'one_hot_encode' \| 'label_encode' \| 'log_transform' \| 'binning' \| 'embedding'>` | optional | | -| **required** | `boolean` | optional | | -| **defaultValue** | `any` | optional | | -| **description** | `string` | optional | | -| **importance** | `number` | optional | Feature importance score (0-1) | diff --git a/content/docs/references/ai/predictive/PredictionRequest.mdx b/content/docs/references/ai/predictive/PredictionRequest.mdx deleted file mode 100644 index 99279567d..000000000 --- a/content/docs/references/ai/predictive/PredictionRequest.mdx +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: PredictionRequest -description: PredictionRequest Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **modelName** | `string` | ✅ | Model to use for prediction | -| **recordIds** | `string[]` | optional | Specific records to predict (if not provided, uses all) | -| **inputData** | `Record` | optional | Direct input data (alternative to recordIds) | -| **returnConfidence** | `boolean` | optional | | -| **returnExplanation** | `boolean` | optional | | diff --git a/content/docs/references/ai/predictive/PredictionResult.mdx b/content/docs/references/ai/predictive/PredictionResult.mdx deleted file mode 100644 index 6c9a6c525..000000000 --- a/content/docs/references/ai/predictive/PredictionResult.mdx +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: PredictionResult -description: PredictionResult Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **modelName** | `string` | ✅ | | -| **modelVersion** | `string` | ✅ | | -| **recordId** | `string` | optional | | -| **prediction** | `any` | optional | The predicted value | -| **confidence** | `number` | optional | Confidence score (0-1) | -| **probabilities** | `Record` | optional | Class probabilities (for classification) | -| **explanation** | `object` | optional | | -| **metadata** | `object` | optional | | diff --git a/content/docs/references/ai/predictive/PredictiveModel.mdx b/content/docs/references/ai/predictive/PredictiveModel.mdx deleted file mode 100644 index f408f1297..000000000 --- a/content/docs/references/ai/predictive/PredictiveModel.mdx +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: PredictiveModel -description: PredictiveModel Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Model unique identifier (snake_case) | -| **label** | `string` | ✅ | Model display name | -| **description** | `string` | optional | | -| **type** | `Enum<'classification' \| 'regression' \| 'clustering' \| 'forecasting' \| 'anomaly_detection' \| 'recommendation' \| 'ranking'>` | ✅ | | -| **algorithm** | `string` | optional | Specific algorithm (e.g., "random_forest", "xgboost", "lstm") | -| **objectName** | `string` | ✅ | Target object for predictions | -| **target** | `string` | ✅ | Target field to predict | -| **targetType** | `Enum<'numeric' \| 'categorical' \| 'binary'>` | optional | Target field type | -| **features** | `object[]` | ✅ | Input features for the model | -| **hyperparameters** | `object` | optional | | -| **training** | `object` | optional | | -| **metrics** | `object` | optional | Evaluation metrics from last training | -| **deploymentStatus** | `Enum<'draft' \| 'training' \| 'trained' \| 'deployed' \| 'deprecated'>` | optional | | -| **version** | `string` | optional | | -| **predictionField** | `string` | optional | Field to store predictions | -| **confidenceField** | `string` | optional | Field to store confidence scores | -| **updateTrigger** | `Enum<'on_create' \| 'on_update' \| 'manual' \| 'scheduled'>` | optional | | -| **autoRetrain** | `boolean` | optional | | -| **retrainSchedule** | `string` | optional | Cron expression for auto-retraining | -| **retrainThreshold** | `number` | optional | Performance threshold to trigger retraining | -| **enableExplainability** | `boolean` | optional | Generate feature importance & explanations | -| **enableMonitoring** | `boolean` | optional | | -| **alertOnDrift** | `boolean` | optional | Alert when model drift is detected | -| **active** | `boolean` | optional | | -| **owner** | `string` | optional | User ID of model owner | -| **permissions** | `string[]` | optional | User/group IDs with access | -| **tags** | `string[]` | optional | | -| **category** | `string` | optional | Model category (e.g., "sales", "marketing", "operations") | -| **lastTrainedAt** | `string` | optional | ISO timestamp | -| **createdAt** | `string` | optional | ISO timestamp | -| **updatedAt** | `string` | optional | ISO timestamp | diff --git a/content/docs/references/ai/predictive/PredictiveModelType.mdx b/content/docs/references/ai/predictive/PredictiveModelType.mdx deleted file mode 100644 index b32506628..000000000 --- a/content/docs/references/ai/predictive/PredictiveModelType.mdx +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: PredictiveModelType -description: PredictiveModelType Schema Reference ---- - -## Allowed Values - -* `classification` -* `regression` -* `clustering` -* `forecasting` -* `anomaly_detection` -* `recommendation` -* `ranking` \ No newline at end of file diff --git a/content/docs/references/ai/predictive/TrainingConfig.mdx b/content/docs/references/ai/predictive/TrainingConfig.mdx deleted file mode 100644 index f42a11d1b..000000000 --- a/content/docs/references/ai/predictive/TrainingConfig.mdx +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: TrainingConfig -description: TrainingConfig Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **trainingDataRatio** | `number` | optional | Proportion of data for training | -| **validationDataRatio** | `number` | optional | Proportion for validation | -| **testDataRatio** | `number` | optional | Proportion for testing | -| **dataFilter** | `string` | optional | Formula to filter training data | -| **minRecords** | `integer` | optional | Minimum records required | -| **maxRecords** | `integer` | optional | Maximum records to use | -| **strategy** | `Enum<'full' \| 'incremental' \| 'online' \| 'transfer_learning'>` | optional | | -| **crossValidation** | `boolean` | optional | | -| **folds** | `integer` | optional | Cross-validation folds | -| **earlyStoppingEnabled** | `boolean` | optional | | -| **earlyStoppingPatience** | `integer` | optional | Epochs without improvement before stopping | -| **maxTrainingTime** | `number` | optional | Maximum training time in seconds | -| **gpuEnabled** | `boolean` | optional | | -| **randomSeed** | `integer` | optional | Random seed for reproducibility | diff --git a/content/docs/references/ai/predictive/meta.json b/content/docs/references/ai/predictive/meta.json deleted file mode 100644 index 4a6c858c1..000000000 --- a/content/docs/references/ai/predictive/meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "title": "Predictive" -} \ No newline at end of file diff --git a/content/docs/references/ai/rag-pipeline.mdx b/content/docs/references/ai/rag-pipeline.mdx new file mode 100644 index 000000000..6456c7519 --- /dev/null +++ b/content/docs/references/ai/rag-pipeline.mdx @@ -0,0 +1,216 @@ +--- +title: Rag Pipeline +description: Rag Pipeline protocol schemas +--- + +# Rag Pipeline + + +**Source:** `packages/spec/src/ai/rag-pipeline.zod.ts` + + +## TypeScript Usage + +```typescript +import { ChunkingStrategySchema, DocumentChunkSchema, DocumentLoaderConfigSchema, DocumentMetadataSchema, EmbeddingModelSchema, RAGPipelineConfigSchema, RAGPipelineStatusSchema, RAGQueryRequestSchema, RAGQueryResponseSchema, RerankingConfigSchema, RetrievalStrategySchema, VectorStoreConfigSchema, VectorStoreProviderSchema } from '@objectstack/spec/ai'; +import type { ChunkingStrategy, DocumentChunk, DocumentLoaderConfig, DocumentMetadata, EmbeddingModel, RAGPipelineConfig, RAGPipelineStatus, RAGQueryRequest, RAGQueryResponse, RerankingConfig, RetrievalStrategy, VectorStoreConfig, VectorStoreProvider } from '@objectstack/spec/ai'; + +// Validate data +const result = ChunkingStrategySchema.parse(data); +``` + +--- + +## ChunkingStrategy + +--- + +## DocumentChunk + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | ✅ | Unique chunk identifier | +| **content** | `string` | ✅ | Chunk text content | +| **embedding** | `number[]` | optional | Embedding vector | +| **metadata** | `object` | ✅ | | +| **chunkIndex** | `integer` | ✅ | Chunk position in document | +| **tokens** | `integer` | optional | Token count | + +--- + +## DocumentLoaderConfig + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **type** | `Enum<'file' \| 'directory' \| 'url' \| 'api' \| 'database' \| 'custom'>` | ✅ | | +| **source** | `string` | ✅ | Source path, URL, or identifier | +| **fileTypes** | `string[]` | optional | Accepted file extensions (e.g., [".pdf", ".md"]) | +| **recursive** | `boolean` | optional | Process directories recursively | +| **maxFileSize** | `integer` | optional | Maximum file size in bytes | +| **excludePatterns** | `string[]` | optional | Patterns to exclude | +| **extractImages** | `boolean` | optional | Extract text from images (OCR) | +| **extractTables** | `boolean` | optional | Extract and format tables | +| **loaderConfig** | `Record` | optional | Custom loader-specific config | + +--- + +## DocumentMetadata + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **source** | `string` | ✅ | Document source (file path, URL, etc.) | +| **sourceType** | `Enum<'file' \| 'url' \| 'api' \| 'database' \| 'custom'>` | optional | | +| **title** | `string` | optional | | +| **author** | `string` | optional | | +| **createdAt** | `string` | optional | ISO timestamp | +| **updatedAt** | `string` | optional | ISO timestamp | +| **tags** | `string[]` | optional | | +| **category** | `string` | optional | | +| **language** | `string` | optional | Document language (ISO 639-1 code) | +| **custom** | `Record` | optional | Custom metadata fields | + +--- + +## EmbeddingModel + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **provider** | `Enum<'openai' \| 'cohere' \| 'huggingface' \| 'azure_openai' \| 'local' \| 'custom'>` | ✅ | | +| **model** | `string` | ✅ | Model name (e.g., "text-embedding-3-large") | +| **dimensions** | `integer` | ✅ | Embedding vector dimensions | +| **maxTokens** | `integer` | optional | Maximum tokens per embedding | +| **batchSize** | `integer` | optional | Batch size for embedding | +| **endpoint** | `string` | optional | Custom endpoint URL | +| **apiKey** | `string` | optional | API key or reference to secret | + +--- + +## RAGPipelineConfig + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Pipeline name (snake_case) | +| **label** | `string` | ✅ | Display name | +| **description** | `string` | optional | | +| **embedding** | `object` | ✅ | | +| **vectorStore** | `object` | ✅ | | +| **chunking** | `object \| object \| object \| object` | ✅ | | +| **retrieval** | `object \| object \| object \| object` | ✅ | | +| **reranking** | `object` | optional | | +| **loaders** | `object[]` | optional | Document loaders | +| **maxContextTokens** | `integer` | optional | Maximum tokens in context | +| **contextWindow** | `integer` | optional | LLM context window size | +| **metadataFilters** | `Record` | optional | Filters for retrieval (e.g., `{category: "docs", status: "published"}`) | +| **enableCache** | `boolean` | optional | | +| **cacheTTL** | `integer` | optional | Cache TTL in seconds | +| **cacheInvalidationStrategy** | `Enum<'time_based' \| 'manual' \| 'on_update'>` | optional | | + +--- + +## RAGPipelineStatus + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | | +| **status** | `Enum<'active' \| 'indexing' \| 'error' \| 'disabled'>` | ✅ | | +| **documentsIndexed** | `integer` | ✅ | | +| **lastIndexed** | `string` | optional | ISO timestamp | +| **errorMessage** | `string` | optional | | +| **health** | `object` | optional | | + +--- + +## RAGQueryRequest + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **query** | `string` | ✅ | User query | +| **pipelineName** | `string` | ✅ | Pipeline to use | +| **topK** | `integer` | optional | | +| **metadataFilters** | `Record` | optional | | +| **conversationHistory** | `object[]` | optional | | +| **includeMetadata** | `boolean` | optional | | +| **includeSources** | `boolean` | optional | | + +--- + +## RAGQueryResponse + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **query** | `string` | ✅ | | +| **results** | `object[]` | ✅ | | +| **context** | `string` | ✅ | Assembled context for LLM | +| **tokensUsed** | `integer` | optional | | +| **retrievalTime** | `number` | optional | Retrieval time in milliseconds | + +--- + +## RerankingConfig + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **enabled** | `boolean` | optional | | +| **model** | `string` | optional | Reranking model name | +| **provider** | `Enum<'cohere' \| 'huggingface' \| 'custom'>` | optional | | +| **topK** | `integer` | optional | Final number of results after reranking | + +--- + +## RetrievalStrategy + +--- + +## VectorStoreConfig + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **provider** | `Enum<'pinecone' \| 'weaviate' \| 'qdrant' \| 'milvus' \| 'chroma' \| 'pgvector' \| 'redis' \| 'opensearch' \| 'elasticsearch' \| 'custom'>` | ✅ | | +| **indexName** | `string` | ✅ | Index/collection name | +| **namespace** | `string` | optional | Namespace for multi-tenancy | +| **host** | `string` | optional | Vector store host | +| **port** | `integer` | optional | Vector store port | +| **apiKey** | `string` | optional | API key or reference to secret | +| **dimensions** | `integer` | ✅ | Vector dimensions | +| **metric** | `Enum<'cosine' \| 'euclidean' \| 'dotproduct'>` | optional | | +| **batchSize** | `integer` | optional | | +| **connectionPoolSize** | `integer` | optional | | +| **timeout** | `integer` | optional | Timeout in milliseconds | + +--- + +## VectorStoreProvider + +### Allowed Values + +* `pinecone` +* `weaviate` +* `qdrant` +* `milvus` +* `chroma` +* `pgvector` +* `redis` +* `opensearch` +* `elasticsearch` +* `custom` + diff --git a/content/docs/references/ai/rag-pipeline/ChunkingStrategy.mdx b/content/docs/references/ai/rag-pipeline/ChunkingStrategy.mdx deleted file mode 100644 index ccb091681..000000000 --- a/content/docs/references/ai/rag-pipeline/ChunkingStrategy.mdx +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: ChunkingStrategy -description: ChunkingStrategy Schema Reference ---- - diff --git a/content/docs/references/ai/rag-pipeline/DocumentChunk.mdx b/content/docs/references/ai/rag-pipeline/DocumentChunk.mdx deleted file mode 100644 index d6d97907c..000000000 --- a/content/docs/references/ai/rag-pipeline/DocumentChunk.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: DocumentChunk -description: DocumentChunk Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Unique chunk identifier | -| **content** | `string` | ✅ | Chunk text content | -| **embedding** | `number[]` | optional | Embedding vector | -| **metadata** | `object` | ✅ | | -| **chunkIndex** | `integer` | ✅ | Chunk position in document | -| **tokens** | `integer` | optional | Token count | diff --git a/content/docs/references/ai/rag-pipeline/DocumentLoaderConfig.mdx b/content/docs/references/ai/rag-pipeline/DocumentLoaderConfig.mdx deleted file mode 100644 index 887ac300b..000000000 --- a/content/docs/references/ai/rag-pipeline/DocumentLoaderConfig.mdx +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: DocumentLoaderConfig -description: DocumentLoaderConfig Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `Enum<'file' \| 'directory' \| 'url' \| 'api' \| 'database' \| 'custom'>` | ✅ | | -| **source** | `string` | ✅ | Source path, URL, or identifier | -| **fileTypes** | `string[]` | optional | Accepted file extensions (e.g., [".pdf", ".md"]) | -| **recursive** | `boolean` | optional | Process directories recursively | -| **maxFileSize** | `integer` | optional | Maximum file size in bytes | -| **excludePatterns** | `string[]` | optional | Patterns to exclude | -| **extractImages** | `boolean` | optional | Extract text from images (OCR) | -| **extractTables** | `boolean` | optional | Extract and format tables | -| **loaderConfig** | `Record` | optional | Custom loader-specific config | diff --git a/content/docs/references/ai/rag-pipeline/DocumentMetadata.mdx b/content/docs/references/ai/rag-pipeline/DocumentMetadata.mdx deleted file mode 100644 index ae125abea..000000000 --- a/content/docs/references/ai/rag-pipeline/DocumentMetadata.mdx +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: DocumentMetadata -description: DocumentMetadata Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **source** | `string` | ✅ | Document source (file path, URL, etc.) | -| **sourceType** | `Enum<'file' \| 'url' \| 'api' \| 'database' \| 'custom'>` | optional | | -| **title** | `string` | optional | | -| **author** | `string` | optional | | -| **createdAt** | `string` | optional | ISO timestamp | -| **updatedAt** | `string` | optional | ISO timestamp | -| **tags** | `string[]` | optional | | -| **category** | `string` | optional | | -| **language** | `string` | optional | Document language (ISO 639-1 code) | -| **custom** | `Record` | optional | Custom metadata fields | diff --git a/content/docs/references/ai/rag-pipeline/EmbeddingModel.mdx b/content/docs/references/ai/rag-pipeline/EmbeddingModel.mdx deleted file mode 100644 index 7d581b2a7..000000000 --- a/content/docs/references/ai/rag-pipeline/EmbeddingModel.mdx +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: EmbeddingModel -description: EmbeddingModel Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **provider** | `Enum<'openai' \| 'cohere' \| 'huggingface' \| 'azure_openai' \| 'local' \| 'custom'>` | ✅ | | -| **model** | `string` | ✅ | Model name (e.g., "text-embedding-3-large") | -| **dimensions** | `integer` | ✅ | Embedding vector dimensions | -| **maxTokens** | `integer` | optional | Maximum tokens per embedding | -| **batchSize** | `integer` | optional | Batch size for embedding | -| **endpoint** | `string` | optional | Custom endpoint URL | -| **apiKey** | `string` | optional | API key or reference to secret | diff --git a/content/docs/references/ai/rag-pipeline/RAGPipelineConfig.mdx b/content/docs/references/ai/rag-pipeline/RAGPipelineConfig.mdx deleted file mode 100644 index 74f5433d8..000000000 --- a/content/docs/references/ai/rag-pipeline/RAGPipelineConfig.mdx +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: RAGPipelineConfig -description: RAGPipelineConfig Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Pipeline name (snake_case) | -| **label** | `string` | ✅ | Display name | -| **description** | `string` | optional | | -| **embedding** | `object` | ✅ | | -| **vectorStore** | `object` | ✅ | | -| **chunking** | `object \| object \| object \| object` | ✅ | | -| **retrieval** | `object \| object \| object \| object` | ✅ | | -| **reranking** | `object` | optional | | -| **loaders** | `object[]` | optional | Document loaders | -| **maxContextTokens** | `integer` | optional | Maximum tokens in context | -| **contextWindow** | `integer` | optional | LLM context window size | -| **metadataFilters** | `Record` | optional | Filters for retrieval (e.g., `{category: "docs", status: "published"}`) | -| **enableCache** | `boolean` | optional | | -| **cacheTTL** | `integer` | optional | Cache TTL in seconds | -| **cacheInvalidationStrategy** | `Enum<'time_based' \| 'manual' \| 'on_update'>` | optional | | diff --git a/content/docs/references/ai/rag-pipeline/RAGPipelineStatus.mdx b/content/docs/references/ai/rag-pipeline/RAGPipelineStatus.mdx deleted file mode 100644 index daffa4d88..000000000 --- a/content/docs/references/ai/rag-pipeline/RAGPipelineStatus.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: RAGPipelineStatus -description: RAGPipelineStatus Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | | -| **status** | `Enum<'active' \| 'indexing' \| 'error' \| 'disabled'>` | ✅ | | -| **documentsIndexed** | `integer` | ✅ | | -| **lastIndexed** | `string` | optional | ISO timestamp | -| **errorMessage** | `string` | optional | | -| **health** | `object` | optional | | diff --git a/content/docs/references/ai/rag-pipeline/RAGQueryRequest.mdx b/content/docs/references/ai/rag-pipeline/RAGQueryRequest.mdx deleted file mode 100644 index 734d8aad0..000000000 --- a/content/docs/references/ai/rag-pipeline/RAGQueryRequest.mdx +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: RAGQueryRequest -description: RAGQueryRequest Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **query** | `string` | ✅ | User query | -| **pipelineName** | `string` | ✅ | Pipeline to use | -| **topK** | `integer` | optional | | -| **metadataFilters** | `Record` | optional | | -| **conversationHistory** | `object[]` | optional | | -| **includeMetadata** | `boolean` | optional | | -| **includeSources** | `boolean` | optional | | diff --git a/content/docs/references/ai/rag-pipeline/RAGQueryResponse.mdx b/content/docs/references/ai/rag-pipeline/RAGQueryResponse.mdx deleted file mode 100644 index d33cdad27..000000000 --- a/content/docs/references/ai/rag-pipeline/RAGQueryResponse.mdx +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: RAGQueryResponse -description: RAGQueryResponse Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **query** | `string` | ✅ | | -| **results** | `object[]` | ✅ | | -| **context** | `string` | ✅ | Assembled context for LLM | -| **tokensUsed** | `integer` | optional | | -| **retrievalTime** | `number` | optional | Retrieval time in milliseconds | diff --git a/content/docs/references/ai/rag-pipeline/RerankingConfig.mdx b/content/docs/references/ai/rag-pipeline/RerankingConfig.mdx deleted file mode 100644 index 7cfb7e3d9..000000000 --- a/content/docs/references/ai/rag-pipeline/RerankingConfig.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: RerankingConfig -description: RerankingConfig Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | optional | | -| **model** | `string` | optional | Reranking model name | -| **provider** | `Enum<'cohere' \| 'huggingface' \| 'custom'>` | optional | | -| **topK** | `integer` | optional | Final number of results after reranking | diff --git a/content/docs/references/ai/rag-pipeline/RetrievalStrategy.mdx b/content/docs/references/ai/rag-pipeline/RetrievalStrategy.mdx deleted file mode 100644 index 25d9e6dde..000000000 --- a/content/docs/references/ai/rag-pipeline/RetrievalStrategy.mdx +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: RetrievalStrategy -description: RetrievalStrategy Schema Reference ---- - diff --git a/content/docs/references/ai/rag-pipeline/VectorStoreConfig.mdx b/content/docs/references/ai/rag-pipeline/VectorStoreConfig.mdx deleted file mode 100644 index db3bd3fbd..000000000 --- a/content/docs/references/ai/rag-pipeline/VectorStoreConfig.mdx +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: VectorStoreConfig -description: VectorStoreConfig Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **provider** | `Enum<'pinecone' \| 'weaviate' \| 'qdrant' \| 'milvus' \| 'chroma' \| 'pgvector' \| 'redis' \| 'opensearch' \| 'elasticsearch' \| 'custom'>` | ✅ | | -| **indexName** | `string` | ✅ | Index/collection name | -| **namespace** | `string` | optional | Namespace for multi-tenancy | -| **host** | `string` | optional | Vector store host | -| **port** | `integer` | optional | Vector store port | -| **apiKey** | `string` | optional | API key or reference to secret | -| **dimensions** | `integer` | ✅ | Vector dimensions | -| **metric** | `Enum<'cosine' \| 'euclidean' \| 'dotproduct'>` | optional | | -| **batchSize** | `integer` | optional | | -| **connectionPoolSize** | `integer` | optional | | -| **timeout** | `integer` | optional | Timeout in milliseconds | diff --git a/content/docs/references/ai/rag-pipeline/VectorStoreProvider.mdx b/content/docs/references/ai/rag-pipeline/VectorStoreProvider.mdx deleted file mode 100644 index 37c6435e6..000000000 --- a/content/docs/references/ai/rag-pipeline/VectorStoreProvider.mdx +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: VectorStoreProvider -description: VectorStoreProvider Schema Reference ---- - -## Allowed Values - -* `pinecone` -* `weaviate` -* `qdrant` -* `milvus` -* `chroma` -* `pgvector` -* `redis` -* `opensearch` -* `elasticsearch` -* `custom` \ No newline at end of file diff --git a/content/docs/references/ai/rag-pipeline/meta.json b/content/docs/references/ai/rag-pipeline/meta.json deleted file mode 100644 index b6a1c7267..000000000 --- a/content/docs/references/ai/rag-pipeline/meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "title": "Rag Pipeline" -} \ No newline at end of file diff --git a/content/docs/references/api/contract.mdx b/content/docs/references/api/contract.mdx new file mode 100644 index 000000000..7f0cd9cc2 --- /dev/null +++ b/content/docs/references/api/contract.mdx @@ -0,0 +1,170 @@ +--- +title: Contract +description: Contract protocol schemas +--- + +# Contract + + +**Source:** `packages/spec/src/api/contract.zod.ts` + + +## TypeScript Usage + +```typescript +import { ApiErrorSchema, BaseResponseSchema, BulkRequestSchema, BulkResponseSchema, CreateRequestSchema, DeleteResponseSchema, ExportRequestSchema, ListRecordResponseSchema, ModificationResultSchema, RecordDataSchema, SingleRecordResponseSchema, UpdateRequestSchema } from '@objectstack/spec/api'; +import type { ApiError, BaseResponse, BulkRequest, BulkResponse, CreateRequest, DeleteResponse, ExportRequest, ListRecordResponse, ModificationResult, RecordData, SingleRecordResponse, UpdateRequest } from '@objectstack/spec/api'; + +// Validate data +const result = ApiErrorSchema.parse(data); +``` + +--- + +## ApiError + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **code** | `string` | ✅ | Error code (e.g. validation_error) | +| **message** | `string` | ✅ | Readable error message | +| **details** | `any` | optional | Additional error context (e.g. field validation errors) | + +--- + +## BaseResponse + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **success** | `boolean` | ✅ | Operation success status | +| **error** | `object` | optional | Error details if success is false | +| **meta** | `object` | optional | Response metadata | + +--- + +## BulkRequest + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **records** | `Record[]` | ✅ | Array of records to process | +| **allOrNone** | `boolean` | optional | If true, rollback entire transaction on any failure | + +--- + +## BulkResponse + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **success** | `boolean` | ✅ | Operation success status | +| **error** | `object` | optional | Error details if success is false | +| **meta** | `object` | optional | Response metadata | +| **data** | `object[]` | ✅ | Results for each item in the batch | + +--- + +## CreateRequest + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **data** | `Record` | ✅ | Record data to insert | + +--- + +## DeleteResponse + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **success** | `boolean` | ✅ | Operation success status | +| **error** | `object` | optional | Error details if success is false | +| **meta** | `object` | optional | Response metadata | +| **id** | `string` | ✅ | ID of the deleted record | + +--- + +## ExportRequest + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **object** | `string` | ✅ | Object name (e.g. account) | +| **fields** | `string \| object[]` | optional | Fields to retrieve | +| **where** | `any` | optional | Filtering criteria (WHERE) | +| **orderBy** | `object[]` | optional | Sorting instructions (ORDER BY) | +| **limit** | `number` | optional | Max records to return (LIMIT) | +| **offset** | `number` | optional | Records to skip (OFFSET) | +| **cursor** | `Record` | optional | Cursor for keyset pagination | +| **joins** | `object[]` | optional | Explicit Table Joins | +| **aggregations** | `object[]` | optional | Aggregation functions | +| **groupBy** | `string[]` | optional | GROUP BY fields | +| **having** | `any` | optional | HAVING clause for aggregation filtering | +| **windowFunctions** | `object[]` | optional | Window functions with OVER clause | +| **distinct** | `boolean` | optional | SELECT DISTINCT flag | +| **format** | `Enum<'csv' \| 'json' \| 'xlsx'>` | optional | | + +--- + +## ListRecordResponse + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **success** | `boolean` | ✅ | Operation success status | +| **error** | `object` | optional | Error details if success is false | +| **meta** | `object` | optional | Response metadata | +| **data** | `Record[]` | ✅ | Array of matching records | +| **pagination** | `object` | ✅ | Pagination info | + +--- + +## ModificationResult + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | optional | Record ID if processed | +| **success** | `boolean` | ✅ | | +| **errors** | `object[]` | optional | | + +--- + +## RecordData + +Key-value map of record data + +--- + +## SingleRecordResponse + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **success** | `boolean` | ✅ | Operation success status | +| **error** | `object` | optional | Error details if success is false | +| **meta** | `object` | optional | Response metadata | +| **data** | `Record` | ✅ | The requested or modified record | + +--- + +## UpdateRequest + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **data** | `Record` | ✅ | Partial record data to update | + diff --git a/content/docs/references/api/contract/ApiError.mdx b/content/docs/references/api/contract/ApiError.mdx deleted file mode 100644 index 2f3f78ff1..000000000 --- a/content/docs/references/api/contract/ApiError.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: ApiError -description: ApiError Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **code** | `string` | ✅ | Error code (e.g. validation_error) | -| **message** | `string` | ✅ | Readable error message | -| **details** | `any` | optional | Additional error context (e.g. field validation errors) | diff --git a/content/docs/references/api/contract/BaseResponse.mdx b/content/docs/references/api/contract/BaseResponse.mdx deleted file mode 100644 index c180bace9..000000000 --- a/content/docs/references/api/contract/BaseResponse.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: BaseResponse -description: BaseResponse Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **success** | `boolean` | ✅ | Operation success status | -| **error** | `object` | optional | Error details if success is false | -| **meta** | `object` | optional | Response metadata | diff --git a/content/docs/references/api/contract/BulkRequest.mdx b/content/docs/references/api/contract/BulkRequest.mdx deleted file mode 100644 index 893f2b17a..000000000 --- a/content/docs/references/api/contract/BulkRequest.mdx +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: BulkRequest -description: BulkRequest Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **records** | `Record[]` | ✅ | Array of records to process | -| **allOrNone** | `boolean` | optional | If true, rollback entire transaction on any failure | diff --git a/content/docs/references/api/contract/BulkResponse.mdx b/content/docs/references/api/contract/BulkResponse.mdx deleted file mode 100644 index cc21f18e4..000000000 --- a/content/docs/references/api/contract/BulkResponse.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: BulkResponse -description: BulkResponse Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **success** | `boolean` | ✅ | Operation success status | -| **error** | `object` | optional | Error details if success is false | -| **meta** | `object` | optional | Response metadata | -| **data** | `object[]` | ✅ | Results for each item in the batch | diff --git a/content/docs/references/api/contract/CreateRequest.mdx b/content/docs/references/api/contract/CreateRequest.mdx deleted file mode 100644 index d6dcc398d..000000000 --- a/content/docs/references/api/contract/CreateRequest.mdx +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: CreateRequest -description: CreateRequest Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **data** | `Record` | ✅ | Record data to insert | diff --git a/content/docs/references/api/contract/DeleteResponse.mdx b/content/docs/references/api/contract/DeleteResponse.mdx deleted file mode 100644 index e0123aab8..000000000 --- a/content/docs/references/api/contract/DeleteResponse.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: DeleteResponse -description: DeleteResponse Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **success** | `boolean` | ✅ | Operation success status | -| **error** | `object` | optional | Error details if success is false | -| **meta** | `object` | optional | Response metadata | -| **id** | `string` | ✅ | ID of the deleted record | diff --git a/content/docs/references/api/contract/ExportRequest.mdx b/content/docs/references/api/contract/ExportRequest.mdx deleted file mode 100644 index f559d1d4a..000000000 --- a/content/docs/references/api/contract/ExportRequest.mdx +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: ExportRequest -description: ExportRequest Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **object** | `string` | ✅ | Object name (e.g. account) | -| **fields** | `string \| object[]` | optional | Fields to retrieve | -| **where** | `any` | optional | Filtering criteria (WHERE) | -| **orderBy** | `object[]` | optional | Sorting instructions (ORDER BY) | -| **limit** | `number` | optional | Max records to return (LIMIT) | -| **offset** | `number` | optional | Records to skip (OFFSET) | -| **cursor** | `Record` | optional | Cursor for keyset pagination | -| **joins** | `object[]` | optional | Explicit Table Joins | -| **aggregations** | `object[]` | optional | Aggregation functions | -| **groupBy** | `string[]` | optional | GROUP BY fields | -| **having** | `any` | optional | HAVING clause for aggregation filtering | -| **windowFunctions** | `object[]` | optional | Window functions with OVER clause | -| **distinct** | `boolean` | optional | SELECT DISTINCT flag | -| **format** | `Enum<'csv' \| 'json' \| 'xlsx'>` | optional | | diff --git a/content/docs/references/api/contract/ListRecordResponse.mdx b/content/docs/references/api/contract/ListRecordResponse.mdx deleted file mode 100644 index 8a69a402c..000000000 --- a/content/docs/references/api/contract/ListRecordResponse.mdx +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: ListRecordResponse -description: ListRecordResponse Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **success** | `boolean` | ✅ | Operation success status | -| **error** | `object` | optional | Error details if success is false | -| **meta** | `object` | optional | Response metadata | -| **data** | `Record[]` | ✅ | Array of matching records | -| **pagination** | `object` | ✅ | Pagination info | diff --git a/content/docs/references/api/contract/ModificationResult.mdx b/content/docs/references/api/contract/ModificationResult.mdx deleted file mode 100644 index 0498f7c62..000000000 --- a/content/docs/references/api/contract/ModificationResult.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: ModificationResult -description: ModificationResult Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | optional | Record ID if processed | -| **success** | `boolean` | ✅ | | -| **errors** | `object[]` | optional | | diff --git a/content/docs/references/api/contract/RecordData.mdx b/content/docs/references/api/contract/RecordData.mdx deleted file mode 100644 index a3a8d02c1..000000000 --- a/content/docs/references/api/contract/RecordData.mdx +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: RecordData -description: Key-value map of record data ---- - -Key-value map of record data - diff --git a/content/docs/references/api/contract/SingleRecordResponse.mdx b/content/docs/references/api/contract/SingleRecordResponse.mdx deleted file mode 100644 index 30b52d855..000000000 --- a/content/docs/references/api/contract/SingleRecordResponse.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: SingleRecordResponse -description: SingleRecordResponse Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **success** | `boolean` | ✅ | Operation success status | -| **error** | `object` | optional | Error details if success is false | -| **meta** | `object` | optional | Response metadata | -| **data** | `Record` | ✅ | The requested or modified record | diff --git a/content/docs/references/api/contract/UpdateRequest.mdx b/content/docs/references/api/contract/UpdateRequest.mdx deleted file mode 100644 index f358d946c..000000000 --- a/content/docs/references/api/contract/UpdateRequest.mdx +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: UpdateRequest -description: UpdateRequest Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **data** | `Record` | ✅ | Partial record data to update | diff --git a/content/docs/references/api/contract/meta.json b/content/docs/references/api/contract/meta.json deleted file mode 100644 index 4676f39a2..000000000 --- a/content/docs/references/api/contract/meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "title": "Contract" -} \ No newline at end of file diff --git a/content/docs/references/api/discovery.mdx b/content/docs/references/api/discovery.mdx new file mode 100644 index 000000000..317f32033 --- /dev/null +++ b/content/docs/references/api/discovery.mdx @@ -0,0 +1,64 @@ +--- +title: Discovery +description: Discovery protocol schemas +--- + +# Discovery + + +**Source:** `packages/spec/src/api/discovery.zod.ts` + + +## TypeScript Usage + +```typescript +import { ApiCapabilitiesSchema, ApiRoutesSchema, DiscoverySchema } from '@objectstack/spec/api'; +import type { ApiCapabilities, ApiRoutes, Discovery } from '@objectstack/spec/api'; + +// Validate data +const result = ApiCapabilitiesSchema.parse(data); +``` + +--- + +## ApiCapabilities + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **graphql** | `boolean` | optional | | +| **search** | `boolean` | optional | | +| **websockets** | `boolean` | optional | | +| **files** | `boolean` | optional | | + +--- + +## ApiRoutes + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **data** | `string` | ✅ | e.g. /api/data | +| **metadata** | `string` | ✅ | e.g. /api/meta | +| **auth** | `string` | ✅ | e.g. /api/auth | +| **automation** | `string` | optional | e.g. /api/automation | +| **storage** | `string` | optional | e.g. /api/storage | +| **graphql** | `string` | optional | e.g. /graphql | + +--- + +## Discovery + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | | +| **version** | `string` | ✅ | | +| **environment** | `Enum<'production' \| 'sandbox' \| 'development'>` | ✅ | | +| **routes** | `object` | ✅ | | +| **features** | `object` | ✅ | | +| **locale** | `object` | ✅ | | + diff --git a/content/docs/references/api/discovery/ApiCapabilities.mdx b/content/docs/references/api/discovery/ApiCapabilities.mdx deleted file mode 100644 index ba39b55e8..000000000 --- a/content/docs/references/api/discovery/ApiCapabilities.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: ApiCapabilities -description: ApiCapabilities Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **graphql** | `boolean` | optional | | -| **search** | `boolean` | optional | | -| **websockets** | `boolean` | optional | | -| **files** | `boolean` | optional | | diff --git a/content/docs/references/api/discovery/ApiRoutes.mdx b/content/docs/references/api/discovery/ApiRoutes.mdx deleted file mode 100644 index 1acb16320..000000000 --- a/content/docs/references/api/discovery/ApiRoutes.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: ApiRoutes -description: ApiRoutes Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **data** | `string` | ✅ | e.g. /api/data | -| **metadata** | `string` | ✅ | e.g. /api/meta | -| **auth** | `string` | ✅ | e.g. /api/auth | -| **automation** | `string` | optional | e.g. /api/automation | -| **storage** | `string` | optional | e.g. /api/storage | -| **graphql** | `string` | optional | e.g. /graphql | diff --git a/content/docs/references/api/discovery/Discovery.mdx b/content/docs/references/api/discovery/Discovery.mdx deleted file mode 100644 index 3dbf27d14..000000000 --- a/content/docs/references/api/discovery/Discovery.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: Discovery -description: Discovery Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | | -| **version** | `string` | ✅ | | -| **environment** | `Enum<'production' \| 'sandbox' \| 'development'>` | ✅ | | -| **routes** | `object` | ✅ | | -| **features** | `object` | ✅ | | -| **locale** | `object` | ✅ | | diff --git a/content/docs/references/api/discovery/meta.json b/content/docs/references/api/discovery/meta.json deleted file mode 100644 index dd5e6e9d5..000000000 --- a/content/docs/references/api/discovery/meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "title": "Discovery" -} \ No newline at end of file diff --git a/content/docs/references/api/endpoint.mdx b/content/docs/references/api/endpoint.mdx new file mode 100644 index 000000000..d4028bd00 --- /dev/null +++ b/content/docs/references/api/endpoint.mdx @@ -0,0 +1,67 @@ +--- +title: Endpoint +description: Endpoint protocol schemas +--- + +# Endpoint + + +**Source:** `packages/spec/src/api/endpoint.zod.ts` + + +## TypeScript Usage + +```typescript +import { ApiEndpointSchema, ApiMappingSchema, RateLimitSchema } from '@objectstack/spec/api'; +import type { ApiEndpoint, ApiMapping, RateLimit } from '@objectstack/spec/api'; + +// Validate data +const result = ApiEndpointSchema.parse(data); +``` + +--- + +## ApiEndpoint + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Unique endpoint ID | +| **path** | `string` | ✅ | URL Path (e.g. /api/v1/customers) | +| **method** | `Enum<'GET' \| 'POST' \| 'PUT' \| 'DELETE' \| 'PATCH' \| 'HEAD' \| 'OPTIONS'>` | ✅ | HTTP Method | +| **summary** | `string` | optional | | +| **description** | `string` | optional | | +| **type** | `Enum<'flow' \| 'script' \| 'object_operation' \| 'proxy'>` | ✅ | Implementation type | +| **target** | `string` | ✅ | Target Flow ID, Script Name, or Proxy URL | +| **objectParams** | `object` | optional | For object_operation type | +| **inputMapping** | `object[]` | optional | Map Request Body to Internal Params | +| **outputMapping** | `object[]` | optional | Map Internal Result to Response Body | +| **authRequired** | `boolean` | optional | Require authentication | +| **rateLimit** | `object` | optional | Rate limiting policy | +| **cacheTtl** | `number` | optional | Response cache TTL in seconds | + +--- + +## ApiMapping + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **source** | `string` | ✅ | Source field/path | +| **target** | `string` | ✅ | Target field/path | +| **transform** | `string` | optional | Transformation function name | + +--- + +## RateLimit + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **enabled** | `boolean` | optional | | +| **windowMs** | `number` | optional | Time window in milliseconds | +| **maxRequests** | `number` | optional | Max requests per window | + diff --git a/content/docs/references/api/endpoint/ApiEndpoint.mdx b/content/docs/references/api/endpoint/ApiEndpoint.mdx deleted file mode 100644 index 48aa4ccba..000000000 --- a/content/docs/references/api/endpoint/ApiEndpoint.mdx +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: ApiEndpoint -description: ApiEndpoint Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Unique endpoint ID | -| **path** | `string` | ✅ | URL Path (e.g. /api/v1/customers) | -| **method** | `Enum<'GET' \| 'POST' \| 'PUT' \| 'DELETE' \| 'PATCH' \| 'HEAD' \| 'OPTIONS'>` | ✅ | HTTP Method | -| **summary** | `string` | optional | | -| **description** | `string` | optional | | -| **type** | `Enum<'flow' \| 'script' \| 'object_operation' \| 'proxy'>` | ✅ | Implementation type | -| **target** | `string` | ✅ | Target Flow ID, Script Name, or Proxy URL | -| **objectParams** | `object` | optional | For object_operation type | -| **inputMapping** | `object[]` | optional | Map Request Body to Internal Params | -| **outputMapping** | `object[]` | optional | Map Internal Result to Response Body | -| **authRequired** | `boolean` | optional | Require authentication | -| **rateLimit** | `object` | optional | Rate limiting policy | -| **cacheTtl** | `number` | optional | Response cache TTL in seconds | diff --git a/content/docs/references/api/endpoint/ApiMapping.mdx b/content/docs/references/api/endpoint/ApiMapping.mdx deleted file mode 100644 index d3ebafe16..000000000 --- a/content/docs/references/api/endpoint/ApiMapping.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: ApiMapping -description: ApiMapping Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **source** | `string` | ✅ | Source field/path | -| **target** | `string` | ✅ | Target field/path | -| **transform** | `string` | optional | Transformation function name | diff --git a/content/docs/references/api/endpoint/RateLimit.mdx b/content/docs/references/api/endpoint/RateLimit.mdx deleted file mode 100644 index 84ebaf8fd..000000000 --- a/content/docs/references/api/endpoint/RateLimit.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: RateLimit -description: RateLimit Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | optional | | -| **windowMs** | `number` | optional | Time window in milliseconds | -| **maxRequests** | `number` | optional | Max requests per window | diff --git a/content/docs/references/api/endpoint/meta.json b/content/docs/references/api/endpoint/meta.json deleted file mode 100644 index 1a36a9f9c..000000000 --- a/content/docs/references/api/endpoint/meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "title": "Endpoint" -} \ No newline at end of file diff --git a/content/docs/references/api/index.mdx b/content/docs/references/api/index.mdx new file mode 100644 index 000000000..764e3f46c --- /dev/null +++ b/content/docs/references/api/index.mdx @@ -0,0 +1,18 @@ +--- +title: API Protocol Overview +description: Complete reference for all api protocol schemas +--- + +# API Protocol + +This section contains all protocol schemas for the api layer of ObjectStack. + + + + + + + + + + diff --git a/content/docs/references/api/odata.mdx b/content/docs/references/api/odata.mdx new file mode 100644 index 000000000..87468810e --- /dev/null +++ b/content/docs/references/api/odata.mdx @@ -0,0 +1,130 @@ +--- +title: Odata +description: Odata protocol schemas +--- + +# Odata + + +**Source:** `packages/spec/src/api/odata.zod.ts` + + +## TypeScript Usage + +```typescript +import { ODataErrorSchema, ODataFilterFunctionSchema, ODataFilterOperatorSchema, ODataMetadataSchema, ODataQuerySchema, ODataResponseSchema } from '@objectstack/spec/api'; +import type { ODataError, ODataFilterFunction, ODataFilterOperator, ODataMetadata, ODataQuery, ODataResponse } from '@objectstack/spec/api'; + +// Validate data +const result = ODataErrorSchema.parse(data); +``` + +--- + +## ODataError + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **error** | `object` | ✅ | | + +--- + +## ODataFilterFunction + +### Allowed Values + +* `contains` +* `startswith` +* `endswith` +* `length` +* `indexof` +* `substring` +* `tolower` +* `toupper` +* `trim` +* `concat` +* `year` +* `month` +* `day` +* `hour` +* `minute` +* `second` +* `date` +* `time` +* `now` +* `maxdatetime` +* `mindatetime` +* `round` +* `floor` +* `ceiling` +* `cast` +* `isof` +* `any` +* `all` + +--- + +## ODataFilterOperator + +### Allowed Values + +* `eq` +* `ne` +* `lt` +* `le` +* `gt` +* `ge` +* `and` +* `or` +* `not` +* `(` +* `)` +* `in` +* `has` + +--- + +## ODataMetadata + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **namespace** | `string` | ✅ | Service namespace | +| **entityTypes** | `object[]` | ✅ | Entity types | +| **entitySets** | `object[]` | ✅ | Entity sets | + +--- + +## ODataQuery + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **$select** | `string \| string[]` | optional | Fields to select | +| **$filter** | `string` | optional | Filter expression (OData filter syntax) | +| **$orderby** | `string \| string[]` | optional | Sort order | +| **$top** | `integer` | optional | Max results to return | +| **$skip** | `integer` | optional | Results to skip | +| **$expand** | `string \| string[]` | optional | Navigation properties to expand | +| **$count** | `boolean` | optional | Include total count | +| **$search** | `string` | optional | Search expression | +| **$format** | `Enum<'json' \| 'xml' \| 'atom'>` | optional | Response format | +| **$apply** | `string` | optional | Aggregation expression | + +--- + +## ODataResponse + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **@odata.context** | `string` | optional | Metadata context URL | +| **@odata.count** | `integer` | optional | Total results count | +| **@odata.nextLink** | `string` | optional | Next page URL | +| **value** | `Record[]` | ✅ | Results array | + diff --git a/content/docs/references/api/odata/ODataError.mdx b/content/docs/references/api/odata/ODataError.mdx deleted file mode 100644 index 54a3c00ad..000000000 --- a/content/docs/references/api/odata/ODataError.mdx +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: ODataError -description: ODataError Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **error** | `object` | ✅ | | diff --git a/content/docs/references/api/odata/ODataFilterFunction.mdx b/content/docs/references/api/odata/ODataFilterFunction.mdx deleted file mode 100644 index 32f6d0c4d..000000000 --- a/content/docs/references/api/odata/ODataFilterFunction.mdx +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: ODataFilterFunction -description: ODataFilterFunction Schema Reference ---- - -## Allowed Values - -* `contains` -* `startswith` -* `endswith` -* `length` -* `indexof` -* `substring` -* `tolower` -* `toupper` -* `trim` -* `concat` -* `year` -* `month` -* `day` -* `hour` -* `minute` -* `second` -* `date` -* `time` -* `now` -* `maxdatetime` -* `mindatetime` -* `round` -* `floor` -* `ceiling` -* `cast` -* `isof` -* `any` -* `all` \ No newline at end of file diff --git a/content/docs/references/api/odata/ODataFilterOperator.mdx b/content/docs/references/api/odata/ODataFilterOperator.mdx deleted file mode 100644 index 0b10a8105..000000000 --- a/content/docs/references/api/odata/ODataFilterOperator.mdx +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: ODataFilterOperator -description: ODataFilterOperator Schema Reference ---- - -## Allowed Values - -* `eq` -* `ne` -* `lt` -* `le` -* `gt` -* `ge` -* `and` -* `or` -* `not` -* `(` -* `)` -* `in` -* `has` \ No newline at end of file diff --git a/content/docs/references/api/odata/ODataMetadata.mdx b/content/docs/references/api/odata/ODataMetadata.mdx deleted file mode 100644 index 10d1432ab..000000000 --- a/content/docs/references/api/odata/ODataMetadata.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: ODataMetadata -description: ODataMetadata Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **namespace** | `string` | ✅ | Service namespace | -| **entityTypes** | `object[]` | ✅ | Entity types | -| **entitySets** | `object[]` | ✅ | Entity sets | diff --git a/content/docs/references/api/odata/ODataQuery.mdx b/content/docs/references/api/odata/ODataQuery.mdx deleted file mode 100644 index 2fba78ae9..000000000 --- a/content/docs/references/api/odata/ODataQuery.mdx +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: ODataQuery -description: ODataQuery Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **$select** | `string \| string[]` | optional | Fields to select | -| **$filter** | `string` | optional | Filter expression (OData filter syntax) | -| **$orderby** | `string \| string[]` | optional | Sort order | -| **$top** | `integer` | optional | Max results to return | -| **$skip** | `integer` | optional | Results to skip | -| **$expand** | `string \| string[]` | optional | Navigation properties to expand | -| **$count** | `boolean` | optional | Include total count | -| **$search** | `string` | optional | Search expression | -| **$format** | `Enum<'json' \| 'xml' \| 'atom'>` | optional | Response format | -| **$apply** | `string` | optional | Aggregation expression | diff --git a/content/docs/references/api/odata/ODataResponse.mdx b/content/docs/references/api/odata/ODataResponse.mdx deleted file mode 100644 index c282d6b0f..000000000 --- a/content/docs/references/api/odata/ODataResponse.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: ODataResponse -description: ODataResponse Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **@odata.context** | `string` | optional | Metadata context URL | -| **@odata.count** | `integer` | optional | Total results count | -| **@odata.nextLink** | `string` | optional | Next page URL | -| **value** | `Record[]` | ✅ | Results array | diff --git a/content/docs/references/api/odata/meta.json b/content/docs/references/api/odata/meta.json deleted file mode 100644 index e030c4de3..000000000 --- a/content/docs/references/api/odata/meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "title": "Odata" -} \ No newline at end of file diff --git a/content/docs/references/api/realtime.mdx b/content/docs/references/api/realtime.mdx new file mode 100644 index 000000000..9532ed757 --- /dev/null +++ b/content/docs/references/api/realtime.mdx @@ -0,0 +1,116 @@ +--- +title: Realtime +description: Realtime protocol schemas +--- + +# Realtime + + +**Source:** `packages/spec/src/api/realtime.zod.ts` + + +## TypeScript Usage + +```typescript +import { PresenceSchema, PresenceStatusSchema, RealtimeActionSchema, RealtimeEventSchema, RealtimeEventTypeSchema, SubscriptionSchema, SubscriptionEventSchema, TransportProtocolSchema } from '@objectstack/spec/api'; +import type { Presence, PresenceStatus, RealtimeAction, RealtimeEvent, RealtimeEventType, Subscription, SubscriptionEvent, TransportProtocol } from '@objectstack/spec/api'; + +// Validate data +const result = PresenceSchema.parse(data); +``` + +--- + +## Presence + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **userId** | `string` | ✅ | User identifier | +| **status** | `Enum<'online' \| 'away' \| 'offline'>` | ✅ | Current presence status | +| **lastSeen** | `string` | ✅ | ISO 8601 datetime of last activity | +| **metadata** | `Record` | optional | Custom presence data (e.g., current page, custom status) | + +--- + +## PresenceStatus + +### Allowed Values + +* `online` +* `away` +* `offline` + +--- + +## RealtimeAction + +### Allowed Values + +* `created` +* `updated` +* `deleted` + +--- + +## RealtimeEvent + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | ✅ | Unique event identifier | +| **type** | `string` | ✅ | Event type (e.g., record.created, record.updated) | +| **object** | `string` | optional | Object name the event relates to | +| **action** | `Enum<'created' \| 'updated' \| 'deleted'>` | optional | Action performed | +| **payload** | `any` | optional | Event payload data | +| **timestamp** | `string` | ✅ | ISO 8601 datetime when event occurred | +| **userId** | `string` | optional | User who triggered the event | + +--- + +## RealtimeEventType + +### Allowed Values + +* `record.created` +* `record.updated` +* `record.deleted` +* `field.changed` + +--- + +## Subscription + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | ✅ | Unique subscription identifier | +| **events** | `object[]` | ✅ | Array of events to subscribe to | +| **transport** | `Enum<'websocket' \| 'sse' \| 'polling'>` | ✅ | Transport protocol to use | +| **channel** | `string` | optional | Optional channel name for grouping subscriptions | + +--- + +## SubscriptionEvent + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **type** | `Enum<'record.created' \| 'record.updated' \| 'record.deleted' \| 'field.changed'>` | ✅ | Type of event to subscribe to | +| **object** | `string` | optional | Object name to subscribe to | +| **filters** | `any` | optional | Filter conditions | + +--- + +## TransportProtocol + +### Allowed Values + +* `websocket` +* `sse` +* `polling` + diff --git a/content/docs/references/api/realtime/Presence.mdx b/content/docs/references/api/realtime/Presence.mdx deleted file mode 100644 index 014e96053..000000000 --- a/content/docs/references/api/realtime/Presence.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Presence -description: Presence Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **userId** | `string` | ✅ | User identifier | -| **status** | `Enum<'online' \| 'away' \| 'offline'>` | ✅ | Current presence status | -| **lastSeen** | `string` | ✅ | ISO 8601 datetime of last activity | -| **metadata** | `Record` | optional | Custom presence data (e.g., current page, custom status) | diff --git a/content/docs/references/api/realtime/PresenceStatus.mdx b/content/docs/references/api/realtime/PresenceStatus.mdx deleted file mode 100644 index f884a53c3..000000000 --- a/content/docs/references/api/realtime/PresenceStatus.mdx +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: PresenceStatus -description: PresenceStatus Schema Reference ---- - -## Allowed Values - -* `online` -* `away` -* `offline` \ No newline at end of file diff --git a/content/docs/references/api/realtime/RealtimeAction.mdx b/content/docs/references/api/realtime/RealtimeAction.mdx deleted file mode 100644 index 2f1af2e3c..000000000 --- a/content/docs/references/api/realtime/RealtimeAction.mdx +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: RealtimeAction -description: RealtimeAction Schema Reference ---- - -## Allowed Values - -* `created` -* `updated` -* `deleted` \ No newline at end of file diff --git a/content/docs/references/api/realtime/RealtimeEvent.mdx b/content/docs/references/api/realtime/RealtimeEvent.mdx deleted file mode 100644 index 46a1b1b22..000000000 --- a/content/docs/references/api/realtime/RealtimeEvent.mdx +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: RealtimeEvent -description: RealtimeEvent Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Unique event identifier | -| **type** | `string` | ✅ | Event type (e.g., record.created, record.updated) | -| **object** | `string` | optional | Object name the event relates to | -| **action** | `Enum<'created' \| 'updated' \| 'deleted'>` | optional | Action performed | -| **payload** | `any` | optional | Event payload data | -| **timestamp** | `string` | ✅ | ISO 8601 datetime when event occurred | -| **userId** | `string` | optional | User who triggered the event | diff --git a/content/docs/references/api/realtime/RealtimeEventType.mdx b/content/docs/references/api/realtime/RealtimeEventType.mdx deleted file mode 100644 index 56c877e5c..000000000 --- a/content/docs/references/api/realtime/RealtimeEventType.mdx +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: RealtimeEventType -description: RealtimeEventType Schema Reference ---- - -## Allowed Values - -* `record.created` -* `record.updated` -* `record.deleted` -* `field.changed` \ No newline at end of file diff --git a/content/docs/references/api/realtime/Subscription.mdx b/content/docs/references/api/realtime/Subscription.mdx deleted file mode 100644 index 31ad739bb..000000000 --- a/content/docs/references/api/realtime/Subscription.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Subscription -description: Subscription Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Unique subscription identifier | -| **events** | `object[]` | ✅ | Array of events to subscribe to | -| **transport** | `Enum<'websocket' \| 'sse' \| 'polling'>` | ✅ | Transport protocol to use | -| **channel** | `string` | optional | Optional channel name for grouping subscriptions | diff --git a/content/docs/references/api/realtime/SubscriptionEvent.mdx b/content/docs/references/api/realtime/SubscriptionEvent.mdx deleted file mode 100644 index ff9133f31..000000000 --- a/content/docs/references/api/realtime/SubscriptionEvent.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: SubscriptionEvent -description: SubscriptionEvent Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `Enum<'record.created' \| 'record.updated' \| 'record.deleted' \| 'field.changed'>` | ✅ | Type of event to subscribe to | -| **object** | `string` | optional | Object name to subscribe to | -| **filters** | `any` | optional | Filter conditions | diff --git a/content/docs/references/api/realtime/TransportProtocol.mdx b/content/docs/references/api/realtime/TransportProtocol.mdx deleted file mode 100644 index a24a12829..000000000 --- a/content/docs/references/api/realtime/TransportProtocol.mdx +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: TransportProtocol -description: TransportProtocol Schema Reference ---- - -## Allowed Values - -* `websocket` -* `sse` -* `polling` \ No newline at end of file diff --git a/content/docs/references/api/realtime/meta.json b/content/docs/references/api/realtime/meta.json deleted file mode 100644 index f9c14dee9..000000000 --- a/content/docs/references/api/realtime/meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "title": "Realtime" -} \ No newline at end of file diff --git a/content/docs/references/api/router.mdx b/content/docs/references/api/router.mdx new file mode 100644 index 000000000..bfed2ea45 --- /dev/null +++ b/content/docs/references/api/router.mdx @@ -0,0 +1,66 @@ +--- +title: Router +description: Router protocol schemas +--- + +# Router + + +**Source:** `packages/spec/src/api/router.zod.ts` + + +## TypeScript Usage + +```typescript +import { RouteCategorySchema, RouteDefinitionSchema, RouterConfigSchema } from '@objectstack/spec/api'; +import type { RouteCategory, RouteDefinition, RouterConfig } from '@objectstack/spec/api'; + +// Validate data +const result = RouteCategorySchema.parse(data); +``` + +--- + +## RouteCategory + +### Allowed Values + +* `system` +* `api` +* `auth` +* `static` +* `webhook` +* `plugin` + +--- + +## RouteDefinition + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **method** | `Enum<'GET' \| 'POST' \| 'PUT' \| 'DELETE' \| 'PATCH' \| 'HEAD' \| 'OPTIONS'>` | ✅ | | +| **path** | `string` | ✅ | URL Path pattern | +| **category** | `Enum<'system' \| 'api' \| 'auth' \| 'static' \| 'webhook' \| 'plugin'>` | optional | | +| **handler** | `string` | ✅ | Unique handler identifier | +| **summary** | `string` | optional | OpenAPI summary | +| **description** | `string` | optional | OpenAPI description | +| **public** | `boolean` | optional | Is publicly accessible | +| **permissions** | `string[]` | optional | Required permissions | +| **timeout** | `integer` | optional | Execution timeout in ms | +| **rateLimit** | `string` | optional | Rate limit policy name | + +--- + +## RouterConfig + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **basePath** | `string` | optional | Global API prefix | +| **mounts** | `object` | optional | | +| **cors** | `object` | optional | | +| **staticMounts** | `object[]` | optional | | + diff --git a/content/docs/references/api/router/RouteCategory.mdx b/content/docs/references/api/router/RouteCategory.mdx deleted file mode 100644 index 33b9cb4de..000000000 --- a/content/docs/references/api/router/RouteCategory.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: RouteCategory -description: RouteCategory Schema Reference ---- - -## Allowed Values - -* `system` -* `api` -* `auth` -* `static` -* `webhook` -* `plugin` \ No newline at end of file diff --git a/content/docs/references/api/router/RouteDefinition.mdx b/content/docs/references/api/router/RouteDefinition.mdx deleted file mode 100644 index cacb592d8..000000000 --- a/content/docs/references/api/router/RouteDefinition.mdx +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: RouteDefinition -description: RouteDefinition Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **method** | `Enum<'GET' \| 'POST' \| 'PUT' \| 'DELETE' \| 'PATCH' \| 'HEAD' \| 'OPTIONS'>` | ✅ | | -| **path** | `string` | ✅ | URL Path pattern | -| **category** | `Enum<'system' \| 'api' \| 'auth' \| 'static' \| 'webhook' \| 'plugin'>` | optional | | -| **handler** | `string` | ✅ | Unique handler identifier | -| **summary** | `string` | optional | OpenAPI summary | -| **description** | `string` | optional | OpenAPI description | -| **public** | `boolean` | optional | Is publicly accessible | -| **permissions** | `string[]` | optional | Required permissions | -| **timeout** | `integer` | optional | Execution timeout in ms | -| **rateLimit** | `string` | optional | Rate limit policy name | diff --git a/content/docs/references/api/router/RouterConfig.mdx b/content/docs/references/api/router/RouterConfig.mdx deleted file mode 100644 index e4c8d8cf8..000000000 --- a/content/docs/references/api/router/RouterConfig.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: RouterConfig -description: RouterConfig Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **basePath** | `string` | optional | Global API prefix | -| **mounts** | `object` | optional | | -| **cors** | `object` | optional | | -| **staticMounts** | `object[]` | optional | | diff --git a/content/docs/references/api/router/meta.json b/content/docs/references/api/router/meta.json deleted file mode 100644 index ca23566ad..000000000 --- a/content/docs/references/api/router/meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "title": "Router" -} \ No newline at end of file diff --git a/content/docs/references/api/view.mdx b/content/docs/references/api/view.mdx new file mode 100644 index 000000000..1ce01caf7 --- /dev/null +++ b/content/docs/references/api/view.mdx @@ -0,0 +1,35 @@ +--- +title: View +description: View protocol schemas +--- + +# View + + +**Source:** `packages/spec/src/api/view.zod.ts` + + +## TypeScript Usage + +```typescript +import { HttpMethodSchema } from '@objectstack/spec/api'; +import type { HttpMethod } from '@objectstack/spec/api'; + +// Validate data +const result = HttpMethodSchema.parse(data); +``` + +--- + +## HttpMethod + +### Allowed Values + +* `GET` +* `POST` +* `PUT` +* `DELETE` +* `PATCH` +* `HEAD` +* `OPTIONS` + diff --git a/content/docs/references/api/view/HttpMethod.mdx b/content/docs/references/api/view/HttpMethod.mdx deleted file mode 100644 index 742c0c547..000000000 --- a/content/docs/references/api/view/HttpMethod.mdx +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: HttpMethod -description: HttpMethod Schema Reference ---- - -## Allowed Values - -* `GET` -* `POST` -* `PUT` -* `DELETE` -* `PATCH` -* `HEAD` -* `OPTIONS` \ No newline at end of file diff --git a/content/docs/references/auth/config.mdx b/content/docs/references/auth/config.mdx new file mode 100644 index 000000000..f78bdb912 --- /dev/null +++ b/content/docs/references/auth/config.mdx @@ -0,0 +1,326 @@ +--- +title: Config +description: Config protocol schemas +--- + +# Config + + +**Source:** `packages/spec/src/auth/config.zod.ts` + + +## TypeScript Usage + +```typescript +import { AccountLinkingConfigSchema, AuthConfigSchema, AuthPluginConfigSchema, AuthStrategySchema, CSRFConfigSchema, DatabaseAdapterSchema, DatabaseMappingSchema, EmailPasswordConfigSchema, EnterpriseAuthConfigSchema, LDAPConfigSchema, MagicLinkConfigSchema, OAuthProviderSchema, OIDCConfigSchema, PasskeyConfigSchema, RateLimitConfigSchema, SAMLConfigSchema, SessionConfigSchema, StandardAuthProviderSchema, TwoFactorConfigSchema, UserFieldMappingSchema } from '@objectstack/spec/auth'; +import type { AccountLinkingConfig, AuthConfig, AuthPluginConfig, AuthStrategy, CSRFConfig, DatabaseAdapter, DatabaseMapping, EmailPasswordConfig, EnterpriseAuthConfig, LDAPConfig, MagicLinkConfig, OAuthProvider, OIDCConfig, PasskeyConfig, RateLimitConfig, SAMLConfig, SessionConfig, StandardAuthProvider, TwoFactorConfig, UserFieldMapping } from '@objectstack/spec/auth'; + +// Validate data +const result = AccountLinkingConfigSchema.parse(data); +``` + +--- + +## AccountLinkingConfig + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **enabled** | `boolean` | optional | Allow account linking | +| **autoLink** | `boolean` | optional | Automatically link accounts with same email | +| **requireVerification** | `boolean` | optional | Require email verification before linking | + +--- + +## AuthConfig + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Configuration name (snake_case) | +| **label** | `string` | ✅ | Display label | +| **driver** | `string` | optional | The underlying authentication implementation driver | +| **strategies** | `Enum<'email_password' \| 'magic_link' \| 'oauth' \| 'passkey' \| 'otp' \| 'anonymous'>[]` | ✅ | Enabled authentication strategies | +| **baseUrl** | `string` | ✅ | Application base URL | +| **secret** | `string` | ✅ | Secret key for signing (min 32 chars) | +| **emailPassword** | `object` | optional | | +| **magicLink** | `object` | optional | | +| **passkey** | `object` | optional | | +| **oauth** | `object` | optional | | +| **session** | `object` | optional | | +| **rateLimit** | `object` | optional | | +| **csrf** | `object` | optional | | +| **accountLinking** | `object` | optional | | +| **twoFactor** | `object` | optional | | +| **organization** | `object` | optional | Organization/multi-tenant configuration | +| **enterprise** | `object` | optional | | +| **userFieldMapping** | `object` | optional | | +| **database** | `object` | optional | | +| **mapping** | `object` | optional | | +| **plugins** | `object[]` | optional | | +| **hooks** | `object` | optional | Authentication lifecycle hooks | +| **security** | `object` | optional | Advanced security settings | +| **email** | `object` | optional | Email configuration | +| **ui** | `object` | optional | UI customization | +| **active** | `boolean` | optional | Whether this provider is active | +| **allowRegistration** | `boolean` | optional | Allow new user registration | + +--- + +## AuthPluginConfig + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Plugin name | +| **enabled** | `boolean` | optional | | +| **options** | `Record` | optional | Plugin-specific options | + +--- + +## AuthStrategy + +### Allowed Values + +* `email_password` +* `magic_link` +* `oauth` +* `passkey` +* `otp` +* `anonymous` + +--- + +## CSRFConfig + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **enabled** | `boolean` | optional | | +| **tokenLength** | `number` | optional | CSRF token length | +| **cookieName** | `string` | optional | CSRF cookie name | +| **headerName** | `string` | optional | CSRF header name | + +--- + +## DatabaseAdapter + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **type** | `Enum<'prisma' \| 'drizzle' \| 'kysely' \| 'custom'>` | ✅ | Database adapter type | +| **connectionString** | `string` | optional | Database connection string | +| **tablePrefix** | `string` | optional | Prefix for auth tables | +| **schema** | `string` | optional | Database schema name | + +--- + +## DatabaseMapping + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **user** | `Record` | optional | User field mapping (e.g., `{ "emailVerified": "email_verified" }`) | +| **session** | `Record` | optional | Session field mapping | +| **account** | `Record` | optional | Account field mapping | +| **verificationToken** | `Record` | optional | VerificationToken field mapping | + +--- + +## EmailPasswordConfig + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **enabled** | `boolean` | optional | | +| **requireEmailVerification** | `boolean` | optional | Require email verification before login | +| **minPasswordLength** | `number` | optional | Minimum password length | +| **requirePasswordComplexity** | `boolean` | optional | Require uppercase, lowercase, numbers, symbols | +| **allowPasswordReset** | `boolean` | optional | Enable password reset functionality | +| **passwordResetExpiry** | `number` | optional | Password reset token expiry in seconds | + +--- + +## EnterpriseAuthConfig + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **oidc** | `object` | optional | OpenID Connect configuration | +| **saml** | `object` | optional | SAML 2.0 configuration | +| **ldap** | `object` | optional | LDAP/Active Directory configuration | + +--- + +## LDAPConfig + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **enabled** | `boolean` | optional | | +| **url** | `string` | ✅ | LDAP Server URL (ldap:// or ldaps://) | +| **bindDn** | `string` | ✅ | Bind DN for LDAP authentication | +| **bindCredentials** | `string` | ✅ | Bind credentials | +| **searchBase** | `string` | ✅ | Search base DN | +| **searchFilter** | `string` | ✅ | Search filter | +| **groupSearchBase** | `string` | optional | Group search base DN | +| **displayName** | `string` | optional | Display name for the provider button | +| **icon** | `string` | optional | Icon URL or identifier | + +--- + +## MagicLinkConfig + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **enabled** | `boolean` | optional | | +| **expiryTime** | `number` | optional | Magic link expiry time in seconds (default 15 min) | + +--- + +## OAuthProvider + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **provider** | `Enum<'google' \| 'github' \| 'facebook' \| 'twitter' \| 'linkedin' \| 'microsoft' \| 'apple' \| 'discord' \| 'gitlab' \| 'custom'>` | ✅ | OAuth provider type | +| **clientId** | `string` | ✅ | OAuth client ID | +| **clientSecret** | `string` | ✅ | OAuth client secret (typically from ENV) | +| **scopes** | `string[]` | optional | Requested OAuth scopes | +| **redirectUri** | `string` | optional | OAuth callback URL | +| **enabled** | `boolean` | optional | Whether this provider is enabled | +| **displayName** | `string` | optional | Display name for the provider button | +| **icon** | `string` | optional | Icon URL or identifier | + +--- + +## OIDCConfig + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **enabled** | `boolean` | optional | | +| **issuer** | `string` | ✅ | OIDC Issuer URL (.well-known/openid-configuration) | +| **clientId** | `string` | ✅ | OIDC client ID | +| **clientSecret** | `string` | ✅ | OIDC client secret | +| **scopes** | `string[]` | optional | OIDC scopes | +| **attributeMapping** | `Record` | optional | Map IdP claims to User fields | +| **displayName** | `string` | optional | Display name for the provider button | +| **icon** | `string` | optional | Icon URL or identifier | + +--- + +## PasskeyConfig + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **enabled** | `boolean` | optional | | +| **rpName** | `string` | ✅ | Relying Party name | +| **rpId** | `string` | optional | Relying Party ID (defaults to domain) | +| **allowedOrigins** | `string[]` | optional | Allowed origins for WebAuthn | +| **userVerification** | `Enum<'required' \| 'preferred' \| 'discouraged'>` | optional | | +| **attestation** | `Enum<'none' \| 'indirect' \| 'direct' \| 'enterprise'>` | optional | | + +--- + +## RateLimitConfig + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **enabled** | `boolean` | optional | | +| **maxAttempts** | `number` | optional | Maximum login attempts | +| **windowMs** | `number` | optional | Time window in milliseconds (default 15 min) | +| **blockDuration** | `number` | optional | Block duration after max attempts in ms | +| **skipSuccessfulRequests** | `boolean` | optional | Only count failed requests | + +--- + +## SAMLConfig + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **enabled** | `boolean` | optional | | +| **entryPoint** | `string` | ✅ | IdP SSO URL | +| **cert** | `string` | ✅ | IdP Public Certificate (PEM format) | +| **issuer** | `string` | ✅ | Entity ID of the IdP | +| **signatureAlgorithm** | `Enum<'sha256' \| 'sha512'>` | optional | Signature algorithm | +| **attributeMapping** | `Record` | optional | Map SAML attributes to User fields | +| **displayName** | `string` | optional | Display name for the provider button | +| **icon** | `string` | optional | Icon URL or identifier | + +--- + +## SessionConfig + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **expiresIn** | `number` | optional | Session expiry in seconds (default 7 days) | +| **updateAge** | `number` | optional | Session update interval in seconds (default 1 day) | +| **cookieName** | `string` | optional | Session cookie name | +| **cookieSecure** | `boolean` | optional | Use secure cookies (HTTPS only) | +| **cookieSameSite** | `Enum<'strict' \| 'lax' \| 'none'>` | optional | SameSite cookie attribute | +| **cookieDomain** | `string` | optional | Cookie domain | +| **cookiePath** | `string` | optional | Cookie path | +| **cookieHttpOnly** | `boolean` | optional | HttpOnly cookie attribute | + +--- + +## StandardAuthProvider + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **type** | `string` | ✅ | Provider type identifier | +| **config** | `object` | ✅ | Standard authentication configuration | + +--- + +## TwoFactorConfig + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **enabled** | `boolean` | optional | | +| **issuer** | `string` | optional | TOTP issuer name | +| **qrCodeSize** | `number` | optional | QR code size in pixels | +| **backupCodes** | `object` | optional | | + +--- + +## UserFieldMapping + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | optional | User ID field | +| **email** | `string` | optional | Email field | +| **name** | `string` | optional | Name field | +| **image** | `string` | optional | Profile image field | +| **emailVerified** | `string` | optional | Email verification status field | +| **createdAt** | `string` | optional | Created timestamp field | +| **updatedAt** | `string` | optional | Updated timestamp field | + diff --git a/content/docs/references/auth/config/AccountLinkingConfig.mdx b/content/docs/references/auth/config/AccountLinkingConfig.mdx deleted file mode 100644 index df6148efd..000000000 --- a/content/docs/references/auth/config/AccountLinkingConfig.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: AccountLinkingConfig -description: AccountLinkingConfig Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | optional | Allow account linking | -| **autoLink** | `boolean` | optional | Automatically link accounts with same email | -| **requireVerification** | `boolean` | optional | Require email verification before linking | diff --git a/content/docs/references/auth/config/AuthConfig.mdx b/content/docs/references/auth/config/AuthConfig.mdx deleted file mode 100644 index 3844175d1..000000000 --- a/content/docs/references/auth/config/AuthConfig.mdx +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: AuthConfig -description: AuthConfig Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Configuration name (snake_case) | -| **label** | `string` | ✅ | Display label | -| **driver** | `string` | optional | The underlying authentication implementation driver | -| **strategies** | `Enum<'email_password' \| 'magic_link' \| 'oauth' \| 'passkey' \| 'otp' \| 'anonymous'>[]` | ✅ | Enabled authentication strategies | -| **baseUrl** | `string` | ✅ | Application base URL | -| **secret** | `string` | ✅ | Secret key for signing (min 32 chars) | -| **emailPassword** | `object` | optional | | -| **magicLink** | `object` | optional | | -| **passkey** | `object` | optional | | -| **oauth** | `object` | optional | | -| **session** | `object` | optional | | -| **rateLimit** | `object` | optional | | -| **csrf** | `object` | optional | | -| **accountLinking** | `object` | optional | | -| **twoFactor** | `object` | optional | | -| **organization** | `object` | optional | Organization/multi-tenant configuration | -| **enterprise** | `object` | optional | | -| **userFieldMapping** | `object` | optional | | -| **database** | `object` | optional | | -| **mapping** | `object` | optional | | -| **plugins** | `object[]` | optional | | -| **hooks** | `object` | optional | Authentication lifecycle hooks | -| **security** | `object` | optional | Advanced security settings | -| **email** | `object` | optional | Email configuration | -| **ui** | `object` | optional | UI customization | -| **active** | `boolean` | optional | Whether this provider is active | -| **allowRegistration** | `boolean` | optional | Allow new user registration | diff --git a/content/docs/references/auth/config/AuthPluginConfig.mdx b/content/docs/references/auth/config/AuthPluginConfig.mdx deleted file mode 100644 index 701df2e7b..000000000 --- a/content/docs/references/auth/config/AuthPluginConfig.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: AuthPluginConfig -description: AuthPluginConfig Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Plugin name | -| **enabled** | `boolean` | optional | | -| **options** | `Record` | optional | Plugin-specific options | diff --git a/content/docs/references/auth/config/AuthStrategy.mdx b/content/docs/references/auth/config/AuthStrategy.mdx deleted file mode 100644 index 9baafb1ad..000000000 --- a/content/docs/references/auth/config/AuthStrategy.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: AuthStrategy -description: AuthStrategy Schema Reference ---- - -## Allowed Values - -* `email_password` -* `magic_link` -* `oauth` -* `passkey` -* `otp` -* `anonymous` \ No newline at end of file diff --git a/content/docs/references/auth/config/CSRFConfig.mdx b/content/docs/references/auth/config/CSRFConfig.mdx deleted file mode 100644 index eba2dddf6..000000000 --- a/content/docs/references/auth/config/CSRFConfig.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: CSRFConfig -description: CSRFConfig Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | optional | | -| **tokenLength** | `number` | optional | CSRF token length | -| **cookieName** | `string` | optional | CSRF cookie name | -| **headerName** | `string` | optional | CSRF header name | diff --git a/content/docs/references/auth/config/DatabaseAdapter.mdx b/content/docs/references/auth/config/DatabaseAdapter.mdx deleted file mode 100644 index 804f75b03..000000000 --- a/content/docs/references/auth/config/DatabaseAdapter.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: DatabaseAdapter -description: DatabaseAdapter Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `Enum<'prisma' \| 'drizzle' \| 'kysely' \| 'custom'>` | ✅ | Database adapter type | -| **connectionString** | `string` | optional | Database connection string | -| **tablePrefix** | `string` | optional | Prefix for auth tables | -| **schema** | `string` | optional | Database schema name | diff --git a/content/docs/references/auth/config/DatabaseMapping.mdx b/content/docs/references/auth/config/DatabaseMapping.mdx deleted file mode 100644 index b618a0b34..000000000 --- a/content/docs/references/auth/config/DatabaseMapping.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: DatabaseMapping -description: DatabaseMapping Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **user** | `Record` | optional | User field mapping (e.g., `{ "emailVerified": "email_verified" }`) | -| **session** | `Record` | optional | Session field mapping | -| **account** | `Record` | optional | Account field mapping | -| **verificationToken** | `Record` | optional | VerificationToken field mapping | diff --git a/content/docs/references/auth/config/EmailPasswordConfig.mdx b/content/docs/references/auth/config/EmailPasswordConfig.mdx deleted file mode 100644 index ed35be72f..000000000 --- a/content/docs/references/auth/config/EmailPasswordConfig.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: EmailPasswordConfig -description: EmailPasswordConfig Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | optional | | -| **requireEmailVerification** | `boolean` | optional | Require email verification before login | -| **minPasswordLength** | `number` | optional | Minimum password length | -| **requirePasswordComplexity** | `boolean` | optional | Require uppercase, lowercase, numbers, symbols | -| **allowPasswordReset** | `boolean` | optional | Enable password reset functionality | -| **passwordResetExpiry** | `number` | optional | Password reset token expiry in seconds | diff --git a/content/docs/references/auth/config/EnterpriseAuthConfig.mdx b/content/docs/references/auth/config/EnterpriseAuthConfig.mdx deleted file mode 100644 index 10df64191..000000000 --- a/content/docs/references/auth/config/EnterpriseAuthConfig.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: EnterpriseAuthConfig -description: EnterpriseAuthConfig Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **oidc** | `object` | optional | OpenID Connect configuration | -| **saml** | `object` | optional | SAML 2.0 configuration | -| **ldap** | `object` | optional | LDAP/Active Directory configuration | diff --git a/content/docs/references/auth/config/LDAPConfig.mdx b/content/docs/references/auth/config/LDAPConfig.mdx deleted file mode 100644 index 1eb470eed..000000000 --- a/content/docs/references/auth/config/LDAPConfig.mdx +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: LDAPConfig -description: LDAPConfig Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | optional | | -| **url** | `string` | ✅ | LDAP Server URL (ldap:// or ldaps://) | -| **bindDn** | `string` | ✅ | Bind DN for LDAP authentication | -| **bindCredentials** | `string` | ✅ | Bind credentials | -| **searchBase** | `string` | ✅ | Search base DN | -| **searchFilter** | `string` | ✅ | Search filter | -| **groupSearchBase** | `string` | optional | Group search base DN | -| **displayName** | `string` | optional | Display name for the provider button | -| **icon** | `string` | optional | Icon URL or identifier | diff --git a/content/docs/references/auth/config/MagicLinkConfig.mdx b/content/docs/references/auth/config/MagicLinkConfig.mdx deleted file mode 100644 index 2971b2862..000000000 --- a/content/docs/references/auth/config/MagicLinkConfig.mdx +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: MagicLinkConfig -description: MagicLinkConfig Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | optional | | -| **expiryTime** | `number` | optional | Magic link expiry time in seconds (default 15 min) | diff --git a/content/docs/references/auth/config/OAuthProvider.mdx b/content/docs/references/auth/config/OAuthProvider.mdx deleted file mode 100644 index 32ff86e83..000000000 --- a/content/docs/references/auth/config/OAuthProvider.mdx +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: OAuthProvider -description: OAuthProvider Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **provider** | `Enum<'google' \| 'github' \| 'facebook' \| 'twitter' \| 'linkedin' \| 'microsoft' \| 'apple' \| 'discord' \| 'gitlab' \| 'custom'>` | ✅ | OAuth provider type | -| **clientId** | `string` | ✅ | OAuth client ID | -| **clientSecret** | `string` | ✅ | OAuth client secret (typically from ENV) | -| **scopes** | `string[]` | optional | Requested OAuth scopes | -| **redirectUri** | `string` | optional | OAuth callback URL | -| **enabled** | `boolean` | optional | Whether this provider is enabled | -| **displayName** | `string` | optional | Display name for the provider button | -| **icon** | `string` | optional | Icon URL or identifier | diff --git a/content/docs/references/auth/config/OIDCConfig.mdx b/content/docs/references/auth/config/OIDCConfig.mdx deleted file mode 100644 index 6b78913d1..000000000 --- a/content/docs/references/auth/config/OIDCConfig.mdx +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: OIDCConfig -description: OIDCConfig Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | optional | | -| **issuer** | `string` | ✅ | OIDC Issuer URL (.well-known/openid-configuration) | -| **clientId** | `string` | ✅ | OIDC client ID | -| **clientSecret** | `string` | ✅ | OIDC client secret | -| **scopes** | `string[]` | optional | OIDC scopes | -| **attributeMapping** | `Record` | optional | Map IdP claims to User fields | -| **displayName** | `string` | optional | Display name for the provider button | -| **icon** | `string` | optional | Icon URL or identifier | diff --git a/content/docs/references/auth/config/PasskeyConfig.mdx b/content/docs/references/auth/config/PasskeyConfig.mdx deleted file mode 100644 index 9e305ed4c..000000000 --- a/content/docs/references/auth/config/PasskeyConfig.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: PasskeyConfig -description: PasskeyConfig Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | optional | | -| **rpName** | `string` | ✅ | Relying Party name | -| **rpId** | `string` | optional | Relying Party ID (defaults to domain) | -| **allowedOrigins** | `string[]` | optional | Allowed origins for WebAuthn | -| **userVerification** | `Enum<'required' \| 'preferred' \| 'discouraged'>` | optional | | -| **attestation** | `Enum<'none' \| 'indirect' \| 'direct' \| 'enterprise'>` | optional | | diff --git a/content/docs/references/auth/config/RateLimitConfig.mdx b/content/docs/references/auth/config/RateLimitConfig.mdx deleted file mode 100644 index 6682505c5..000000000 --- a/content/docs/references/auth/config/RateLimitConfig.mdx +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: RateLimitConfig -description: RateLimitConfig Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | optional | | -| **maxAttempts** | `number` | optional | Maximum login attempts | -| **windowMs** | `number` | optional | Time window in milliseconds (default 15 min) | -| **blockDuration** | `number` | optional | Block duration after max attempts in ms | -| **skipSuccessfulRequests** | `boolean` | optional | Only count failed requests | diff --git a/content/docs/references/auth/config/SAMLConfig.mdx b/content/docs/references/auth/config/SAMLConfig.mdx deleted file mode 100644 index 6a25ee832..000000000 --- a/content/docs/references/auth/config/SAMLConfig.mdx +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: SAMLConfig -description: SAMLConfig Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | optional | | -| **entryPoint** | `string` | ✅ | IdP SSO URL | -| **cert** | `string` | ✅ | IdP Public Certificate (PEM format) | -| **issuer** | `string` | ✅ | Entity ID of the IdP | -| **signatureAlgorithm** | `Enum<'sha256' \| 'sha512'>` | optional | Signature algorithm | -| **attributeMapping** | `Record` | optional | Map SAML attributes to User fields | -| **displayName** | `string` | optional | Display name for the provider button | -| **icon** | `string` | optional | Icon URL or identifier | diff --git a/content/docs/references/auth/config/SessionConfig.mdx b/content/docs/references/auth/config/SessionConfig.mdx deleted file mode 100644 index 5fb4b1c25..000000000 --- a/content/docs/references/auth/config/SessionConfig.mdx +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: SessionConfig -description: SessionConfig Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **expiresIn** | `number` | optional | Session expiry in seconds (default 7 days) | -| **updateAge** | `number` | optional | Session update interval in seconds (default 1 day) | -| **cookieName** | `string` | optional | Session cookie name | -| **cookieSecure** | `boolean` | optional | Use secure cookies (HTTPS only) | -| **cookieSameSite** | `Enum<'strict' \| 'lax' \| 'none'>` | optional | SameSite cookie attribute | -| **cookieDomain** | `string` | optional | Cookie domain | -| **cookiePath** | `string` | optional | Cookie path | -| **cookieHttpOnly** | `boolean` | optional | HttpOnly cookie attribute | diff --git a/content/docs/references/auth/config/StandardAuthProvider.mdx b/content/docs/references/auth/config/StandardAuthProvider.mdx deleted file mode 100644 index fdc46136f..000000000 --- a/content/docs/references/auth/config/StandardAuthProvider.mdx +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: StandardAuthProvider -description: StandardAuthProvider Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | Provider type identifier | -| **config** | `object` | ✅ | Standard authentication configuration | diff --git a/content/docs/references/auth/config/TwoFactorConfig.mdx b/content/docs/references/auth/config/TwoFactorConfig.mdx deleted file mode 100644 index 70add73db..000000000 --- a/content/docs/references/auth/config/TwoFactorConfig.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: TwoFactorConfig -description: TwoFactorConfig Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | optional | | -| **issuer** | `string` | optional | TOTP issuer name | -| **qrCodeSize** | `number` | optional | QR code size in pixels | -| **backupCodes** | `object` | optional | | diff --git a/content/docs/references/auth/config/UserFieldMapping.mdx b/content/docs/references/auth/config/UserFieldMapping.mdx deleted file mode 100644 index bfbf94d14..000000000 --- a/content/docs/references/auth/config/UserFieldMapping.mdx +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: UserFieldMapping -description: UserFieldMapping Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | optional | User ID field | -| **email** | `string` | optional | Email field | -| **name** | `string` | optional | Name field | -| **image** | `string` | optional | Profile image field | -| **emailVerified** | `string` | optional | Email verification status field | -| **createdAt** | `string` | optional | Created timestamp field | -| **updatedAt** | `string` | optional | Updated timestamp field | diff --git a/content/docs/references/auth/config/meta.json b/content/docs/references/auth/config/meta.json deleted file mode 100644 index 84de464eb..000000000 --- a/content/docs/references/auth/config/meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "title": "Config" -} \ No newline at end of file diff --git a/content/docs/references/auth/identity.mdx b/content/docs/references/auth/identity.mdx new file mode 100644 index 000000000..40b134427 --- /dev/null +++ b/content/docs/references/auth/identity.mdx @@ -0,0 +1,92 @@ +--- +title: Identity +description: Identity protocol schemas +--- + +# Identity + + +**Source:** `packages/spec/src/auth/identity.zod.ts` + + +## TypeScript Usage + +```typescript +import { AccountSchema, SessionSchema, UserSchema, VerificationTokenSchema } from '@objectstack/spec/auth'; +import type { Account, Session, User, VerificationToken } from '@objectstack/spec/auth'; + +// Validate data +const result = AccountSchema.parse(data); +``` + +--- + +## Account + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | ✅ | Unique account identifier | +| **userId** | `string` | ✅ | Associated user ID | +| **type** | `Enum<'oauth' \| 'oidc' \| 'email' \| 'credentials' \| 'saml' \| 'ldap'>` | ✅ | Account type | +| **provider** | `string` | ✅ | Provider name | +| **providerAccountId** | `string` | ✅ | Provider account ID | +| **refreshToken** | `string` | optional | OAuth refresh token | +| **accessToken** | `string` | optional | OAuth access token | +| **expiresAt** | `number` | optional | Token expiry timestamp (Unix) | +| **tokenType** | `string` | optional | OAuth token type | +| **scope** | `string` | optional | OAuth scope | +| **idToken** | `string` | optional | OAuth ID token | +| **sessionState** | `string` | optional | Session state | +| **createdAt** | `string` | ✅ | Account creation timestamp | +| **updatedAt** | `string` | ✅ | Last update timestamp | + +--- + +## Session + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | ✅ | Unique session identifier | +| **sessionToken** | `string` | ✅ | Session token | +| **userId** | `string` | ✅ | Associated user ID | +| **activeOrganizationId** | `string` | optional | Active organization ID for context switching | +| **expires** | `string` | ✅ | Session expiry timestamp | +| **createdAt** | `string` | ✅ | Session creation timestamp | +| **updatedAt** | `string` | ✅ | Last update timestamp | +| **ipAddress** | `string` | optional | IP address | +| **userAgent** | `string` | optional | User agent string | +| **fingerprint** | `string` | optional | Device fingerprint | + +--- + +## User + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | ✅ | Unique user identifier | +| **email** | `string` | ✅ | User email address | +| **emailVerified** | `boolean` | optional | Whether email is verified | +| **name** | `string` | optional | User display name | +| **image** | `string` | optional | Profile image URL | +| **createdAt** | `string` | ✅ | Account creation timestamp | +| **updatedAt** | `string` | ✅ | Last update timestamp | + +--- + +## VerificationToken + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **identifier** | `string` | ✅ | Token identifier (email or phone) | +| **token** | `string` | ✅ | Verification token | +| **expires** | `string` | ✅ | Token expiry timestamp | +| **createdAt** | `string` | ✅ | Token creation timestamp | + diff --git a/content/docs/references/auth/identity/Account.mdx b/content/docs/references/auth/identity/Account.mdx deleted file mode 100644 index 541739381..000000000 --- a/content/docs/references/auth/identity/Account.mdx +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Account -description: Account Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Unique account identifier | -| **userId** | `string` | ✅ | Associated user ID | -| **type** | `Enum<'oauth' \| 'oidc' \| 'email' \| 'credentials' \| 'saml' \| 'ldap'>` | ✅ | Account type | -| **provider** | `string` | ✅ | Provider name | -| **providerAccountId** | `string` | ✅ | Provider account ID | -| **refreshToken** | `string` | optional | OAuth refresh token | -| **accessToken** | `string` | optional | OAuth access token | -| **expiresAt** | `number` | optional | Token expiry timestamp (Unix) | -| **tokenType** | `string` | optional | OAuth token type | -| **scope** | `string` | optional | OAuth scope | -| **idToken** | `string` | optional | OAuth ID token | -| **sessionState** | `string` | optional | Session state | -| **createdAt** | `string` | ✅ | Account creation timestamp | -| **updatedAt** | `string` | ✅ | Last update timestamp | diff --git a/content/docs/references/auth/identity/Session.mdx b/content/docs/references/auth/identity/Session.mdx deleted file mode 100644 index 8423d852a..000000000 --- a/content/docs/references/auth/identity/Session.mdx +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Session -description: Session Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Unique session identifier | -| **sessionToken** | `string` | ✅ | Session token | -| **userId** | `string` | ✅ | Associated user ID | -| **activeOrganizationId** | `string` | optional | Active organization ID for context switching | -| **expires** | `string` | ✅ | Session expiry timestamp | -| **createdAt** | `string` | ✅ | Session creation timestamp | -| **updatedAt** | `string` | ✅ | Last update timestamp | -| **ipAddress** | `string` | optional | IP address | -| **userAgent** | `string` | optional | User agent string | -| **fingerprint** | `string` | optional | Device fingerprint | diff --git a/content/docs/references/auth/identity/User.mdx b/content/docs/references/auth/identity/User.mdx deleted file mode 100644 index baae4accc..000000000 --- a/content/docs/references/auth/identity/User.mdx +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: User -description: User Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Unique user identifier | -| **email** | `string` | ✅ | User email address | -| **emailVerified** | `boolean` | optional | Whether email is verified | -| **name** | `string` | optional | User display name | -| **image** | `string` | optional | Profile image URL | -| **createdAt** | `string` | ✅ | Account creation timestamp | -| **updatedAt** | `string` | ✅ | Last update timestamp | diff --git a/content/docs/references/auth/identity/VerificationToken.mdx b/content/docs/references/auth/identity/VerificationToken.mdx deleted file mode 100644 index ee5f9d034..000000000 --- a/content/docs/references/auth/identity/VerificationToken.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: VerificationToken -description: VerificationToken Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **identifier** | `string` | ✅ | Token identifier (email or phone) | -| **token** | `string` | ✅ | Verification token | -| **expires** | `string` | ✅ | Token expiry timestamp | -| **createdAt** | `string` | ✅ | Token creation timestamp | diff --git a/content/docs/references/auth/identity/meta.json b/content/docs/references/auth/identity/meta.json deleted file mode 100644 index 97df7cd95..000000000 --- a/content/docs/references/auth/identity/meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "title": "Identity" -} \ No newline at end of file diff --git a/content/docs/references/auth/index.mdx b/content/docs/references/auth/index.mdx new file mode 100644 index 000000000..df0b4da8a --- /dev/null +++ b/content/docs/references/auth/index.mdx @@ -0,0 +1,18 @@ +--- +title: Auth Protocol Overview +description: Complete reference for all auth protocol schemas +--- + +# Auth Protocol + +This section contains all protocol schemas for the auth layer of ObjectStack. + + + + + + + + + + diff --git a/content/docs/references/auth/organization.mdx b/content/docs/references/auth/organization.mdx new file mode 100644 index 000000000..31d58abc0 --- /dev/null +++ b/content/docs/references/auth/organization.mdx @@ -0,0 +1,81 @@ +--- +title: Organization +description: Organization protocol schemas +--- + +# Organization + + +**Source:** `packages/spec/src/auth/organization.zod.ts` + + +## TypeScript Usage + +```typescript +import { InvitationSchema, InvitationStatusSchema, MemberSchema, OrganizationSchema } from '@objectstack/spec/auth'; +import type { Invitation, InvitationStatus, Member, Organization } from '@objectstack/spec/auth'; + +// Validate data +const result = InvitationSchema.parse(data); +``` + +--- + +## Invitation + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | ✅ | Unique invitation identifier | +| **organizationId** | `string` | ✅ | Organization ID | +| **email** | `string` | ✅ | Invitee email address | +| **role** | `string` | ✅ | Role to assign upon acceptance | +| **status** | `Enum<'pending' \| 'accepted' \| 'rejected' \| 'expired'>` | optional | Invitation status | +| **expiresAt** | `string` | ✅ | Invitation expiry timestamp | +| **inviterId** | `string` | ✅ | User ID of the inviter | +| **createdAt** | `string` | ✅ | Invitation creation timestamp | +| **updatedAt** | `string` | ✅ | Last update timestamp | + +--- + +## InvitationStatus + +### Allowed Values + +* `pending` +* `accepted` +* `rejected` +* `expired` + +--- + +## Member + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | ✅ | Unique member identifier | +| **organizationId** | `string` | ✅ | Organization ID | +| **userId** | `string` | ✅ | User ID | +| **role** | `string` | ✅ | Member role (e.g., owner, admin, member, guest) | +| **createdAt** | `string` | ✅ | Member creation timestamp | +| **updatedAt** | `string` | ✅ | Last update timestamp | + +--- + +## Organization + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | ✅ | Unique organization identifier | +| **name** | `string` | ✅ | Organization display name | +| **slug** | `string` | ✅ | Unique URL-friendly slug (lowercase alphanumeric, hyphens, underscores) | +| **logo** | `string` | optional | Organization logo URL | +| **metadata** | `Record` | optional | Custom metadata | +| **createdAt** | `string` | ✅ | Organization creation timestamp | +| **updatedAt** | `string` | ✅ | Last update timestamp | + diff --git a/content/docs/references/auth/organization/Invitation.mdx b/content/docs/references/auth/organization/Invitation.mdx deleted file mode 100644 index 6b1dc9901..000000000 --- a/content/docs/references/auth/organization/Invitation.mdx +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Invitation -description: Invitation Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Unique invitation identifier | -| **organizationId** | `string` | ✅ | Organization ID | -| **email** | `string` | ✅ | Invitee email address | -| **role** | `string` | ✅ | Role to assign upon acceptance | -| **status** | `Enum<'pending' \| 'accepted' \| 'rejected' \| 'expired'>` | optional | Invitation status | -| **expiresAt** | `string` | ✅ | Invitation expiry timestamp | -| **inviterId** | `string` | ✅ | User ID of the inviter | -| **createdAt** | `string` | ✅ | Invitation creation timestamp | -| **updatedAt** | `string` | ✅ | Last update timestamp | diff --git a/content/docs/references/auth/organization/InvitationStatus.mdx b/content/docs/references/auth/organization/InvitationStatus.mdx deleted file mode 100644 index 8969996d1..000000000 --- a/content/docs/references/auth/organization/InvitationStatus.mdx +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: InvitationStatus -description: InvitationStatus Schema Reference ---- - -## Allowed Values - -* `pending` -* `accepted` -* `rejected` -* `expired` \ No newline at end of file diff --git a/content/docs/references/auth/organization/Member.mdx b/content/docs/references/auth/organization/Member.mdx deleted file mode 100644 index f02aac973..000000000 --- a/content/docs/references/auth/organization/Member.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: Member -description: Member Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Unique member identifier | -| **organizationId** | `string` | ✅ | Organization ID | -| **userId** | `string` | ✅ | User ID | -| **role** | `string` | ✅ | Member role (e.g., owner, admin, member, guest) | -| **createdAt** | `string` | ✅ | Member creation timestamp | -| **updatedAt** | `string` | ✅ | Last update timestamp | diff --git a/content/docs/references/auth/organization/Organization.mdx b/content/docs/references/auth/organization/Organization.mdx deleted file mode 100644 index 5afbfecce..000000000 --- a/content/docs/references/auth/organization/Organization.mdx +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: Organization -description: Organization Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Unique organization identifier | -| **name** | `string` | ✅ | Organization display name | -| **slug** | `string` | ✅ | Unique URL-friendly slug (lowercase alphanumeric, hyphens, underscores) | -| **logo** | `string` | optional | Organization logo URL | -| **metadata** | `Record` | optional | Custom metadata | -| **createdAt** | `string` | ✅ | Organization creation timestamp | -| **updatedAt** | `string` | ✅ | Last update timestamp | diff --git a/content/docs/references/auth/organization/meta.json b/content/docs/references/auth/organization/meta.json deleted file mode 100644 index 7d2b5f26a..000000000 --- a/content/docs/references/auth/organization/meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "title": "Organization" -} \ No newline at end of file diff --git a/content/docs/references/auth/policy.mdx b/content/docs/references/auth/policy.mdx new file mode 100644 index 000000000..aa2edc0c8 --- /dev/null +++ b/content/docs/references/auth/policy.mdx @@ -0,0 +1,89 @@ +--- +title: Policy +description: Policy protocol schemas +--- + +# Policy + + +**Source:** `packages/spec/src/auth/policy.zod.ts` + + +## TypeScript Usage + +```typescript +import { AuditPolicySchema, NetworkPolicySchema, PasswordPolicySchema, PolicySchema, SessionPolicySchema } from '@objectstack/spec/auth'; +import type { AuditPolicy, NetworkPolicy, PasswordPolicy, Policy, SessionPolicy } from '@objectstack/spec/auth'; + +// Validate data +const result = AuditPolicySchema.parse(data); +``` + +--- + +## AuditPolicy + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **logRetentionDays** | `number` | optional | | +| **sensitiveFields** | `string[]` | ✅ | Fields to redact in logs (e.g. password, ssn) | +| **captureRead** | `boolean` | optional | Log read access (High volume!) | + +--- + +## NetworkPolicy + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **trustedRanges** | `string[]` | ✅ | CIDR ranges allowed to access (e.g. 10.0.0.0/8) | +| **blockUnknown** | `boolean` | optional | Block all IPs not in trusted ranges | +| **vpnRequired** | `boolean` | optional | | + +--- + +## PasswordPolicy + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **minLength** | `number` | optional | | +| **requireUppercase** | `boolean` | optional | | +| **requireLowercase** | `boolean` | optional | | +| **requireNumbers** | `boolean` | optional | | +| **requireSymbols** | `boolean` | optional | | +| **expirationDays** | `number` | optional | Force password change every X days | +| **historyCount** | `number` | optional | Prevent reusing last X passwords | + +--- + +## Policy + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Policy Name | +| **password** | `object` | optional | | +| **network** | `object` | optional | | +| **session** | `object` | optional | | +| **audit** | `object` | optional | | +| **isDefault** | `boolean` | optional | Apply to all users by default | +| **assignedProfiles** | `string[]` | optional | Apply to specific profiles | + +--- + +## SessionPolicy + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **idleTimeout** | `number` | optional | Minutes before idle session logout | +| **absoluteTimeout** | `number` | optional | Max session duration (minutes) | +| **forceMfa** | `boolean` | optional | Require 2FA for all users | + diff --git a/content/docs/references/auth/policy/AuditPolicy.mdx b/content/docs/references/auth/policy/AuditPolicy.mdx deleted file mode 100644 index 9dd0106f9..000000000 --- a/content/docs/references/auth/policy/AuditPolicy.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: AuditPolicy -description: AuditPolicy Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **logRetentionDays** | `number` | optional | | -| **sensitiveFields** | `string[]` | ✅ | Fields to redact in logs (e.g. password, ssn) | -| **captureRead** | `boolean` | optional | Log read access (High volume!) | diff --git a/content/docs/references/auth/policy/NetworkPolicy.mdx b/content/docs/references/auth/policy/NetworkPolicy.mdx deleted file mode 100644 index ce0112852..000000000 --- a/content/docs/references/auth/policy/NetworkPolicy.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: NetworkPolicy -description: NetworkPolicy Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **trustedRanges** | `string[]` | ✅ | CIDR ranges allowed to access (e.g. 10.0.0.0/8) | -| **blockUnknown** | `boolean` | optional | Block all IPs not in trusted ranges | -| **vpnRequired** | `boolean` | optional | | diff --git a/content/docs/references/auth/policy/PasswordPolicy.mdx b/content/docs/references/auth/policy/PasswordPolicy.mdx deleted file mode 100644 index 7d23bd06c..000000000 --- a/content/docs/references/auth/policy/PasswordPolicy.mdx +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: PasswordPolicy -description: PasswordPolicy Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **minLength** | `number` | optional | | -| **requireUppercase** | `boolean` | optional | | -| **requireLowercase** | `boolean` | optional | | -| **requireNumbers** | `boolean` | optional | | -| **requireSymbols** | `boolean` | optional | | -| **expirationDays** | `number` | optional | Force password change every X days | -| **historyCount** | `number` | optional | Prevent reusing last X passwords | diff --git a/content/docs/references/auth/policy/Policy.mdx b/content/docs/references/auth/policy/Policy.mdx deleted file mode 100644 index c143fef9e..000000000 --- a/content/docs/references/auth/policy/Policy.mdx +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: Policy -description: Policy Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Policy Name | -| **password** | `object` | optional | | -| **network** | `object` | optional | | -| **session** | `object` | optional | | -| **audit** | `object` | optional | | -| **isDefault** | `boolean` | optional | Apply to all users by default | -| **assignedProfiles** | `string[]` | optional | Apply to specific profiles | diff --git a/content/docs/references/auth/policy/SessionPolicy.mdx b/content/docs/references/auth/policy/SessionPolicy.mdx deleted file mode 100644 index da62e84af..000000000 --- a/content/docs/references/auth/policy/SessionPolicy.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: SessionPolicy -description: SessionPolicy Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **idleTimeout** | `number` | optional | Minutes before idle session logout | -| **absoluteTimeout** | `number` | optional | Max session duration (minutes) | -| **forceMfa** | `boolean` | optional | Require 2FA for all users | diff --git a/content/docs/references/auth/policy/meta.json b/content/docs/references/auth/policy/meta.json deleted file mode 100644 index 3f7527ca1..000000000 --- a/content/docs/references/auth/policy/meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "title": "Policy" -} \ No newline at end of file diff --git a/content/docs/references/auth/role.mdx b/content/docs/references/auth/role.mdx new file mode 100644 index 000000000..f03d545c7 --- /dev/null +++ b/content/docs/references/auth/role.mdx @@ -0,0 +1,34 @@ +--- +title: Role +description: Role protocol schemas +--- + +# Role + + +**Source:** `packages/spec/src/auth/role.zod.ts` + + +## TypeScript Usage + +```typescript +import { RoleSchema } from '@objectstack/spec/auth'; +import type { Role } from '@objectstack/spec/auth'; + +// Validate data +const result = RoleSchema.parse(data); +``` + +--- + +## Role + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Unique role name (lowercase snake_case) | +| **label** | `string` | ✅ | Display label (e.g. VP of Sales) | +| **parent** | `string` | optional | Parent Role ID (Reports To) | +| **description** | `string` | optional | | + diff --git a/content/docs/references/auth/role/Role.mdx b/content/docs/references/auth/role/Role.mdx deleted file mode 100644 index ad088d0f7..000000000 --- a/content/docs/references/auth/role/Role.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Role -description: Role Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Unique role name (lowercase snake_case) | -| **label** | `string` | ✅ | Display label (e.g. VP of Sales) | -| **parent** | `string` | optional | Parent Role ID (Reports To) | -| **description** | `string` | optional | | diff --git a/content/docs/references/auth/role/meta.json b/content/docs/references/auth/role/meta.json deleted file mode 100644 index 548168cd6..000000000 --- a/content/docs/references/auth/role/meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "title": "Role" -} \ No newline at end of file diff --git a/content/docs/references/auth/scim.mdx b/content/docs/references/auth/scim.mdx new file mode 100644 index 000000000..4295cf9be --- /dev/null +++ b/content/docs/references/auth/scim.mdx @@ -0,0 +1,234 @@ +--- +title: Scim +description: Scim protocol schemas +--- + +# Scim + + +**Source:** `packages/spec/src/auth/scim.zod.ts` + + +## TypeScript Usage + +```typescript +import { SCIMAddressSchema, SCIMEmailSchema, SCIMEnterpriseUserSchema, SCIMErrorSchema, SCIMGroupSchema, SCIMGroupReferenceSchema, SCIMListResponseSchema, SCIMMemberReferenceSchema, SCIMMetaSchema, SCIMNameSchema, SCIMPatchOperationSchema, SCIMPatchRequestSchema, SCIMPhoneNumberSchema, SCIMUserSchema } from '@objectstack/spec/auth'; +import type { SCIMAddress, SCIMEmail, SCIMEnterpriseUser, SCIMError, SCIMGroup, SCIMGroupReference, SCIMListResponse, SCIMMemberReference, SCIMMeta, SCIMName, SCIMPatchOperation, SCIMPatchRequest, SCIMPhoneNumber, SCIMUser } from '@objectstack/spec/auth'; + +// Validate data +const result = SCIMAddressSchema.parse(data); +``` + +--- + +## SCIMAddress + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **formatted** | `string` | optional | Formatted address | +| **streetAddress** | `string` | optional | Street address | +| **locality** | `string` | optional | City/Locality | +| **region** | `string` | optional | State/Region | +| **postalCode** | `string` | optional | Postal code | +| **country** | `string` | optional | Country | +| **type** | `Enum<'work' \| 'home' \| 'other'>` | optional | Address type | +| **primary** | `boolean` | optional | Primary address indicator | + +--- + +## SCIMEmail + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **value** | `string` | ✅ | Email address | +| **type** | `Enum<'work' \| 'home' \| 'other'>` | optional | Email type | +| **display** | `string` | optional | Display label | +| **primary** | `boolean` | optional | Primary email indicator | + +--- + +## SCIMEnterpriseUser + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **employeeNumber** | `string` | optional | Employee number | +| **costCenter** | `string` | optional | Cost center | +| **organization** | `string` | optional | Organization | +| **division** | `string` | optional | Division | +| **department** | `string` | optional | Department | +| **manager** | `object` | optional | Manager reference | + +--- + +## SCIMError + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **schemas** | `string[]` | optional | SCIM schema URIs | +| **status** | `integer` | ✅ | HTTP status code | +| **scimType** | `Enum<'invalidFilter' \| 'tooMany' \| 'uniqueness' \| 'mutability' \| 'invalidSyntax' \| 'invalidPath' \| 'noTarget' \| 'invalidValue' \| 'invalidVers' \| 'sensitive'>` | optional | SCIM error type | +| **detail** | `string` | optional | Error detail message | + +--- + +## SCIMGroup + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **schemas** | `string[]` | optional | SCIM schema URIs (must include Group schema) | +| **id** | `string` | optional | Unique resource identifier | +| **externalId** | `string` | optional | External identifier from client system | +| **displayName** | `string` | ✅ | Group display name (REQUIRED) | +| **members** | `object[]` | optional | Group members | +| **meta** | `object` | optional | Resource metadata | + +--- + +## SCIMGroupReference + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **value** | `string` | ✅ | Group ID | +| **$ref** | `string` | optional | URI reference to the group | +| **display** | `string` | optional | Group display name | +| **type** | `Enum<'direct' \| 'indirect'>` | optional | Membership type | + +--- + +## SCIMListResponse + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **schemas** | `string[]` | optional | SCIM schema URIs | +| **totalResults** | `integer` | ✅ | Total results count | +| **Resources** | `object \| object \| Record[]` | ✅ | Resources array (Users, Groups, or custom resources) | +| **startIndex** | `integer` | optional | Start index (1-based) | +| **itemsPerPage** | `integer` | optional | Items per page | + +--- + +## SCIMMemberReference + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **value** | `string` | ✅ | Member ID | +| **$ref** | `string` | optional | URI reference to the member | +| **type** | `Enum<'User' \| 'Group'>` | optional | Member type | +| **display** | `string` | optional | Member display name | + +--- + +## SCIMMeta + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **resourceType** | `string` | optional | Resource type | +| **created** | `string` | optional | Creation timestamp | +| **lastModified** | `string` | optional | Last modification timestamp | +| **location** | `string` | optional | Resource location URI | +| **version** | `string` | optional | Entity tag (ETag) for concurrency control | + +--- + +## SCIMName + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **formatted** | `string` | optional | Formatted full name | +| **familyName** | `string` | optional | Family name (last name) | +| **givenName** | `string` | optional | Given name (first name) | +| **middleName** | `string` | optional | Middle name | +| **honorificPrefix** | `string` | optional | Honorific prefix (Mr., Ms., Dr.) | +| **honorificSuffix** | `string` | optional | Honorific suffix (Jr., Sr.) | + +--- + +## SCIMPatchOperation + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **op** | `Enum<'add' \| 'remove' \| 'replace'>` | ✅ | Operation type | +| **path** | `string` | optional | Attribute path (optional for add) | +| **value** | `any` | optional | Value to set | + +--- + +## SCIMPatchRequest + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **schemas** | `string[]` | optional | SCIM schema URIs | +| **Operations** | `object[]` | ✅ | Patch operations | + +--- + +## SCIMPhoneNumber + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **value** | `string` | ✅ | Phone number | +| **type** | `Enum<'work' \| 'home' \| 'mobile' \| 'fax' \| 'pager' \| 'other'>` | optional | Phone number type | +| **display** | `string` | optional | Display label | +| **primary** | `boolean` | optional | Primary phone indicator | + +--- + +## SCIMUser + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **schemas** | `string[]` | optional | SCIM schema URIs (must include User schema) | +| **id** | `string` | optional | Unique resource identifier | +| **externalId** | `string` | optional | External identifier from client system | +| **userName** | `string` | ✅ | Unique username (REQUIRED) | +| **name** | `object` | optional | Structured name components | +| **displayName** | `string` | optional | Display name for UI | +| **nickName** | `string` | optional | Nickname | +| **profileUrl** | `string` | optional | Profile page URL | +| **title** | `string` | optional | Job title | +| **userType** | `string` | optional | User type (employee, contractor) | +| **preferredLanguage** | `string` | optional | Preferred language (ISO 639-1) | +| **locale** | `string` | optional | Locale (e.g., en-US) | +| **timezone** | `string` | optional | Timezone | +| **active** | `boolean` | optional | Account active status | +| **password** | `string` | optional | Password (write-only) | +| **emails** | `object[]` | optional | Email addresses | +| **phoneNumbers** | `object[]` | optional | Phone numbers | +| **ims** | `object[]` | optional | IM addresses | +| **photos** | `object[]` | optional | Photo URLs | +| **addresses** | `object[]` | optional | Physical addresses | +| **groups** | `object[]` | optional | Group memberships | +| **entitlements** | `object[]` | optional | Entitlements | +| **roles** | `object[]` | optional | Roles | +| **x509Certificates** | `object[]` | optional | X509 certificates | +| **meta** | `object` | optional | Resource metadata | +| **urn:ietf:params:scim:schemas:extension:enterprise:2.0:User** | `object` | optional | Enterprise user attributes | + diff --git a/content/docs/references/auth/scim/SCIMAddress.mdx b/content/docs/references/auth/scim/SCIMAddress.mdx deleted file mode 100644 index d7af19716..000000000 --- a/content/docs/references/auth/scim/SCIMAddress.mdx +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: SCIMAddress -description: SCIMAddress Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **formatted** | `string` | optional | Formatted address | -| **streetAddress** | `string` | optional | Street address | -| **locality** | `string` | optional | City/Locality | -| **region** | `string` | optional | State/Region | -| **postalCode** | `string` | optional | Postal code | -| **country** | `string` | optional | Country | -| **type** | `Enum<'work' \| 'home' \| 'other'>` | optional | Address type | -| **primary** | `boolean` | optional | Primary address indicator | diff --git a/content/docs/references/auth/scim/SCIMEmail.mdx b/content/docs/references/auth/scim/SCIMEmail.mdx deleted file mode 100644 index 8ac77c635..000000000 --- a/content/docs/references/auth/scim/SCIMEmail.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: SCIMEmail -description: SCIMEmail Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **value** | `string` | ✅ | Email address | -| **type** | `Enum<'work' \| 'home' \| 'other'>` | optional | Email type | -| **display** | `string` | optional | Display label | -| **primary** | `boolean` | optional | Primary email indicator | diff --git a/content/docs/references/auth/scim/SCIMEnterpriseUser.mdx b/content/docs/references/auth/scim/SCIMEnterpriseUser.mdx deleted file mode 100644 index 4d9bf5e38..000000000 --- a/content/docs/references/auth/scim/SCIMEnterpriseUser.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: SCIMEnterpriseUser -description: SCIMEnterpriseUser Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **employeeNumber** | `string` | optional | Employee number | -| **costCenter** | `string` | optional | Cost center | -| **organization** | `string` | optional | Organization | -| **division** | `string` | optional | Division | -| **department** | `string` | optional | Department | -| **manager** | `object` | optional | Manager reference | diff --git a/content/docs/references/auth/scim/SCIMError.mdx b/content/docs/references/auth/scim/SCIMError.mdx deleted file mode 100644 index 11c12b1f6..000000000 --- a/content/docs/references/auth/scim/SCIMError.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: SCIMError -description: SCIMError Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **schemas** | `string[]` | optional | SCIM schema URIs | -| **status** | `integer` | ✅ | HTTP status code | -| **scimType** | `Enum<'invalidFilter' \| 'tooMany' \| 'uniqueness' \| 'mutability' \| 'invalidSyntax' \| 'invalidPath' \| 'noTarget' \| 'invalidValue' \| 'invalidVers' \| 'sensitive'>` | optional | SCIM error type | -| **detail** | `string` | optional | Error detail message | diff --git a/content/docs/references/auth/scim/SCIMGroup.mdx b/content/docs/references/auth/scim/SCIMGroup.mdx deleted file mode 100644 index 73e6d24e7..000000000 --- a/content/docs/references/auth/scim/SCIMGroup.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: SCIMGroup -description: SCIMGroup Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **schemas** | `string[]` | optional | SCIM schema URIs (must include Group schema) | -| **id** | `string` | optional | Unique resource identifier | -| **externalId** | `string` | optional | External identifier from client system | -| **displayName** | `string` | ✅ | Group display name (REQUIRED) | -| **members** | `object[]` | optional | Group members | -| **meta** | `object` | optional | Resource metadata | diff --git a/content/docs/references/auth/scim/SCIMGroupReference.mdx b/content/docs/references/auth/scim/SCIMGroupReference.mdx deleted file mode 100644 index 5a9458643..000000000 --- a/content/docs/references/auth/scim/SCIMGroupReference.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: SCIMGroupReference -description: SCIMGroupReference Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **value** | `string` | ✅ | Group ID | -| **$ref** | `string` | optional | URI reference to the group | -| **display** | `string` | optional | Group display name | -| **type** | `Enum<'direct' \| 'indirect'>` | optional | Membership type | diff --git a/content/docs/references/auth/scim/SCIMListResponse.mdx b/content/docs/references/auth/scim/SCIMListResponse.mdx deleted file mode 100644 index 5c0f6d2c8..000000000 --- a/content/docs/references/auth/scim/SCIMListResponse.mdx +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: SCIMListResponse -description: SCIMListResponse Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **schemas** | `string[]` | optional | SCIM schema URIs | -| **totalResults** | `integer` | ✅ | Total results count | -| **Resources** | `object \| object \| Record[]` | ✅ | Resources array (Users, Groups, or custom resources) | -| **startIndex** | `integer` | optional | Start index (1-based) | -| **itemsPerPage** | `integer` | optional | Items per page | diff --git a/content/docs/references/auth/scim/SCIMMemberReference.mdx b/content/docs/references/auth/scim/SCIMMemberReference.mdx deleted file mode 100644 index e2e05e926..000000000 --- a/content/docs/references/auth/scim/SCIMMemberReference.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: SCIMMemberReference -description: SCIMMemberReference Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **value** | `string` | ✅ | Member ID | -| **$ref** | `string` | optional | URI reference to the member | -| **type** | `Enum<'User' \| 'Group'>` | optional | Member type | -| **display** | `string` | optional | Member display name | diff --git a/content/docs/references/auth/scim/SCIMMeta.mdx b/content/docs/references/auth/scim/SCIMMeta.mdx deleted file mode 100644 index 919cb861b..000000000 --- a/content/docs/references/auth/scim/SCIMMeta.mdx +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: SCIMMeta -description: SCIMMeta Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **resourceType** | `string` | optional | Resource type | -| **created** | `string` | optional | Creation timestamp | -| **lastModified** | `string` | optional | Last modification timestamp | -| **location** | `string` | optional | Resource location URI | -| **version** | `string` | optional | Entity tag (ETag) for concurrency control | diff --git a/content/docs/references/auth/scim/SCIMName.mdx b/content/docs/references/auth/scim/SCIMName.mdx deleted file mode 100644 index 7947a0cdf..000000000 --- a/content/docs/references/auth/scim/SCIMName.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: SCIMName -description: SCIMName Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **formatted** | `string` | optional | Formatted full name | -| **familyName** | `string` | optional | Family name (last name) | -| **givenName** | `string` | optional | Given name (first name) | -| **middleName** | `string` | optional | Middle name | -| **honorificPrefix** | `string` | optional | Honorific prefix (Mr., Ms., Dr.) | -| **honorificSuffix** | `string` | optional | Honorific suffix (Jr., Sr.) | diff --git a/content/docs/references/auth/scim/SCIMPatchOperation.mdx b/content/docs/references/auth/scim/SCIMPatchOperation.mdx deleted file mode 100644 index 2d92e6839..000000000 --- a/content/docs/references/auth/scim/SCIMPatchOperation.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: SCIMPatchOperation -description: SCIMPatchOperation Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **op** | `Enum<'add' \| 'remove' \| 'replace'>` | ✅ | Operation type | -| **path** | `string` | optional | Attribute path (optional for add) | -| **value** | `any` | optional | Value to set | diff --git a/content/docs/references/auth/scim/SCIMPatchRequest.mdx b/content/docs/references/auth/scim/SCIMPatchRequest.mdx deleted file mode 100644 index 17180da9f..000000000 --- a/content/docs/references/auth/scim/SCIMPatchRequest.mdx +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: SCIMPatchRequest -description: SCIMPatchRequest Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **schemas** | `string[]` | optional | SCIM schema URIs | -| **Operations** | `object[]` | ✅ | Patch operations | diff --git a/content/docs/references/auth/scim/SCIMPhoneNumber.mdx b/content/docs/references/auth/scim/SCIMPhoneNumber.mdx deleted file mode 100644 index 8bee2e021..000000000 --- a/content/docs/references/auth/scim/SCIMPhoneNumber.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: SCIMPhoneNumber -description: SCIMPhoneNumber Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **value** | `string` | ✅ | Phone number | -| **type** | `Enum<'work' \| 'home' \| 'mobile' \| 'fax' \| 'pager' \| 'other'>` | optional | Phone number type | -| **display** | `string` | optional | Display label | -| **primary** | `boolean` | optional | Primary phone indicator | diff --git a/content/docs/references/auth/scim/SCIMUser.mdx b/content/docs/references/auth/scim/SCIMUser.mdx deleted file mode 100644 index 5c7cf2379..000000000 --- a/content/docs/references/auth/scim/SCIMUser.mdx +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: SCIMUser -description: SCIMUser Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **schemas** | `string[]` | optional | SCIM schema URIs (must include User schema) | -| **id** | `string` | optional | Unique resource identifier | -| **externalId** | `string` | optional | External identifier from client system | -| **userName** | `string` | ✅ | Unique username (REQUIRED) | -| **name** | `object` | optional | Structured name components | -| **displayName** | `string` | optional | Display name for UI | -| **nickName** | `string` | optional | Nickname | -| **profileUrl** | `string` | optional | Profile page URL | -| **title** | `string` | optional | Job title | -| **userType** | `string` | optional | User type (employee, contractor) | -| **preferredLanguage** | `string` | optional | Preferred language (ISO 639-1) | -| **locale** | `string` | optional | Locale (e.g., en-US) | -| **timezone** | `string` | optional | Timezone | -| **active** | `boolean` | optional | Account active status | -| **password** | `string` | optional | Password (write-only) | -| **emails** | `object[]` | optional | Email addresses | -| **phoneNumbers** | `object[]` | optional | Phone numbers | -| **ims** | `object[]` | optional | IM addresses | -| **photos** | `object[]` | optional | Photo URLs | -| **addresses** | `object[]` | optional | Physical addresses | -| **groups** | `object[]` | optional | Group memberships | -| **entitlements** | `object[]` | optional | Entitlements | -| **roles** | `object[]` | optional | Roles | -| **x509Certificates** | `object[]` | optional | X509 certificates | -| **meta** | `object` | optional | Resource metadata | -| **urn:ietf:params:scim:schemas:extension:enterprise:2.0:User** | `object` | optional | Enterprise user attributes | diff --git a/content/docs/references/auth/scim/meta.json b/content/docs/references/auth/scim/meta.json deleted file mode 100644 index 71b5a3eaf..000000000 --- a/content/docs/references/auth/scim/meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "title": "Scim" -} \ No newline at end of file diff --git a/content/docs/references/automation/approval.mdx b/content/docs/references/automation/approval.mdx new file mode 100644 index 000000000..1fda95f88 --- /dev/null +++ b/content/docs/references/automation/approval.mdx @@ -0,0 +1,95 @@ +--- +title: Approval +description: Approval protocol schemas +--- + +# Approval + + +**Source:** `packages/spec/src/automation/approval.zod.ts` + + +## TypeScript Usage + +```typescript +import { ApprovalActionSchema, ApprovalActionTypeSchema, ApprovalProcessSchema, ApprovalStepSchema, ApproverTypeSchema } from '@objectstack/spec/automation'; +import type { ApprovalAction, ApprovalActionType, ApprovalProcess, ApprovalStep, ApproverType } from '@objectstack/spec/automation'; + +// Validate data +const result = ApprovalActionSchema.parse(data); +``` + +--- + +## ApprovalAction + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **type** | `Enum<'field_update' \| 'email_alert' \| 'webhook' \| 'script'>` | ✅ | | +| **name** | `string` | ✅ | Action name | +| **config** | `Record` | ✅ | Action configuration | + +--- + +## ApprovalActionType + +### Allowed Values + +* `field_update` +* `email_alert` +* `webhook` +* `script` + +--- + +## ApprovalProcess + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Unique process name | +| **label** | `string` | ✅ | Human readable label | +| **object** | `string` | ✅ | Target Object Name | +| **active** | `boolean` | optional | | +| **description** | `string` | optional | | +| **entryCriteria** | `string` | optional | Formula to allow submission | +| **lockRecord** | `boolean` | optional | Lock record from editing during approval | +| **steps** | `object[]` | ✅ | Sequence of approval steps | +| **onSubmit** | `object[]` | optional | Actions on initial submission | +| **onFinalApprove** | `object[]` | optional | Actions on final approval | +| **onFinalReject** | `object[]` | optional | Actions on final rejection | +| **onRecall** | `object[]` | optional | Actions on recall | + +--- + +## ApprovalStep + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Step machine name | +| **label** | `string` | ✅ | Step display label | +| **description** | `string` | optional | | +| **entryCriteria** | `string` | optional | Formula expression to enter this step | +| **approvers** | `object[]` | ✅ | List of allowed approvers | +| **behavior** | `Enum<'first_response' \| 'unanimous'>` | optional | How to handle multiple approvers | +| **rejectionBehavior** | `Enum<'reject_process' \| 'back_to_previous'>` | optional | What happens if rejected | +| **onApprove** | `object[]` | optional | Actions on step approval | +| **onReject** | `object[]` | optional | Actions on step rejection | + +--- + +## ApproverType + +### Allowed Values + +* `user` +* `role` +* `manager` +* `field` +* `queue` + diff --git a/content/docs/references/automation/approval/ApprovalAction.mdx b/content/docs/references/automation/approval/ApprovalAction.mdx deleted file mode 100644 index 479cd8ab0..000000000 --- a/content/docs/references/automation/approval/ApprovalAction.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: ApprovalAction -description: ApprovalAction Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `Enum<'field_update' \| 'email_alert' \| 'webhook' \| 'script'>` | ✅ | | -| **name** | `string` | ✅ | Action name | -| **config** | `Record` | ✅ | Action configuration | diff --git a/content/docs/references/automation/approval/ApprovalActionType.mdx b/content/docs/references/automation/approval/ApprovalActionType.mdx deleted file mode 100644 index d02ae2712..000000000 --- a/content/docs/references/automation/approval/ApprovalActionType.mdx +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: ApprovalActionType -description: ApprovalActionType Schema Reference ---- - -## Allowed Values - -* `field_update` -* `email_alert` -* `webhook` -* `script` \ No newline at end of file diff --git a/content/docs/references/automation/approval/ApprovalProcess.mdx b/content/docs/references/automation/approval/ApprovalProcess.mdx deleted file mode 100644 index 795fbf333..000000000 --- a/content/docs/references/automation/approval/ApprovalProcess.mdx +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: ApprovalProcess -description: ApprovalProcess Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Unique process name | -| **label** | `string` | ✅ | Human readable label | -| **object** | `string` | ✅ | Target Object Name | -| **active** | `boolean` | optional | | -| **description** | `string` | optional | | -| **entryCriteria** | `string` | optional | Formula to allow submission | -| **lockRecord** | `boolean` | optional | Lock record from editing during approval | -| **steps** | `object[]` | ✅ | Sequence of approval steps | -| **onSubmit** | `object[]` | optional | Actions on initial submission | -| **onFinalApprove** | `object[]` | optional | Actions on final approval | -| **onFinalReject** | `object[]` | optional | Actions on final rejection | -| **onRecall** | `object[]` | optional | Actions on recall | diff --git a/content/docs/references/automation/approval/ApprovalStep.mdx b/content/docs/references/automation/approval/ApprovalStep.mdx deleted file mode 100644 index 595ee69bf..000000000 --- a/content/docs/references/automation/approval/ApprovalStep.mdx +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: ApprovalStep -description: ApprovalStep Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Step machine name | -| **label** | `string` | ✅ | Step display label | -| **description** | `string` | optional | | -| **entryCriteria** | `string` | optional | Formula expression to enter this step | -| **approvers** | `object[]` | ✅ | List of allowed approvers | -| **behavior** | `Enum<'first_response' \| 'unanimous'>` | optional | How to handle multiple approvers | -| **rejectionBehavior** | `Enum<'reject_process' \| 'back_to_previous'>` | optional | What happens if rejected | -| **onApprove** | `object[]` | optional | Actions on step approval | -| **onReject** | `object[]` | optional | Actions on step rejection | diff --git a/content/docs/references/automation/approval/ApproverType.mdx b/content/docs/references/automation/approval/ApproverType.mdx deleted file mode 100644 index 46374b980..000000000 --- a/content/docs/references/automation/approval/ApproverType.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: ApproverType -description: ApproverType Schema Reference ---- - -## Allowed Values - -* `user` -* `role` -* `manager` -* `field` -* `queue` \ No newline at end of file diff --git a/content/docs/references/automation/approval/meta.json b/content/docs/references/automation/approval/meta.json deleted file mode 100644 index 4b3e80736..000000000 --- a/content/docs/references/automation/approval/meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "title": "Approval" -} \ No newline at end of file diff --git a/content/docs/references/automation/connector.mdx b/content/docs/references/automation/connector.mdx new file mode 100644 index 000000000..a0363065b --- /dev/null +++ b/content/docs/references/automation/connector.mdx @@ -0,0 +1,211 @@ +--- +title: Connector +description: Connector protocol schemas +--- + +# Connector + + +**Source:** `packages/spec/src/automation/connector.zod.ts` + + +## TypeScript Usage + +```typescript +import { AuthFieldSchema, AuthenticationSchema, AuthenticationTypeSchema, ConnectorSchema, ConnectorCategorySchema, ConnectorInstanceSchema, ConnectorOperationSchema, ConnectorTriggerSchema, OAuth2ConfigSchema, OperationParameterSchema, OperationTypeSchema } from '@objectstack/spec/automation'; +import type { AuthField, Authentication, AuthenticationType, Connector, ConnectorCategory, ConnectorInstance, ConnectorOperation, ConnectorTrigger, OAuth2Config, OperationParameter, OperationType } from '@objectstack/spec/automation'; + +// Validate data +const result = AuthFieldSchema.parse(data); +``` + +--- + +## AuthField + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Field name (snake_case) | +| **label** | `string` | ✅ | Field label | +| **type** | `Enum<'text' \| 'password' \| 'url' \| 'select'>` | optional | Field type | +| **description** | `string` | optional | Field description | +| **required** | `boolean` | optional | Required field | +| **default** | `string` | optional | Default value | +| **options** | `object[]` | optional | Select field options | +| **placeholder** | `string` | optional | Placeholder text | + +--- + +## Authentication + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **type** | `Enum<'none' \| 'apiKey' \| 'basic' \| 'bearer' \| 'oauth1' \| 'oauth2' \| 'custom'>` | ✅ | Authentication type | +| **fields** | `object[]` | optional | Authentication fields | +| **oauth2** | `object` | optional | OAuth 2.0 configuration | +| **test** | `object` | optional | Authentication test configuration | + +--- + +## AuthenticationType + +### Allowed Values + +* `none` +* `apiKey` +* `basic` +* `bearer` +* `oauth1` +* `oauth2` +* `custom` + +--- + +## Connector + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | ✅ | Connector ID (snake_case) | +| **name** | `string` | ✅ | Connector name | +| **description** | `string` | optional | Connector description | +| **version** | `string` | optional | Connector version | +| **icon** | `string` | optional | Connector icon | +| **category** | `Enum<'crm' \| 'payment' \| 'communication' \| 'storage' \| 'analytics' \| 'database' \| 'marketing' \| 'accounting' \| 'hr' \| 'productivity' \| 'ecommerce' \| 'support' \| 'devtools' \| 'social' \| 'other'>` | ✅ | Connector category | +| **baseUrl** | `string` | optional | API base URL | +| **authentication** | `object` | ✅ | Authentication config | +| **operations** | `object[]` | optional | Connector operations | +| **triggers** | `object[]` | optional | Connector triggers | +| **rateLimit** | `object` | optional | Rate limiting | +| **author** | `string` | optional | Connector author | +| **documentation** | `string` | optional | Documentation URL | +| **homepage** | `string` | optional | Homepage URL | +| **license** | `string` | optional | License (SPDX identifier) | +| **tags** | `string[]` | optional | Connector tags | +| **verified** | `boolean` | optional | Verified connector | +| **metadata** | `Record` | optional | Custom metadata | + +--- + +## ConnectorCategory + +### Allowed Values + +* `crm` +* `payment` +* `communication` +* `storage` +* `analytics` +* `database` +* `marketing` +* `accounting` +* `hr` +* `productivity` +* `ecommerce` +* `support` +* `devtools` +* `social` +* `other` + +--- + +## ConnectorInstance + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | ✅ | Instance ID | +| **connectorId** | `string` | ✅ | Connector ID | +| **name** | `string` | ✅ | Instance name | +| **description** | `string` | optional | Instance description | +| **credentials** | `Record` | ✅ | Encrypted credentials | +| **config** | `Record` | optional | Additional config | +| **active** | `boolean` | optional | Instance active status | +| **createdAt** | `string` | optional | Creation time | +| **lastTestedAt** | `string` | optional | Last test time | +| **testStatus** | `Enum<'unknown' \| 'success' \| 'failed'>` | optional | Connection test status | + +--- + +## ConnectorOperation + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | ✅ | Operation ID (snake_case) | +| **name** | `string` | ✅ | Operation name | +| **description** | `string` | optional | Operation description | +| **type** | `Enum<'read' \| 'write' \| 'delete' \| 'search' \| 'trigger' \| 'action'>` | ✅ | Operation type | +| **inputSchema** | `object[]` | optional | Input parameters | +| **outputSchema** | `Record` | optional | Output schema | +| **sampleOutput** | `any` | optional | Sample output | +| **supportsPagination** | `boolean` | optional | Supports pagination | +| **supportsFiltering** | `boolean` | optional | Supports filtering | + +--- + +## ConnectorTrigger + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | ✅ | Trigger ID (snake_case) | +| **name** | `string` | ✅ | Trigger name | +| **description** | `string` | optional | Trigger description | +| **type** | `Enum<'webhook' \| 'polling' \| 'stream'>` | ✅ | Trigger mechanism | +| **config** | `Record` | optional | Trigger configuration | +| **outputSchema** | `Record` | optional | Event payload schema | +| **pollingIntervalMs** | `integer` | optional | Polling interval in ms | + +--- + +## OAuth2Config + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **authorizationUrl** | `string` | ✅ | Authorization endpoint URL | +| **tokenUrl** | `string` | ✅ | Token endpoint URL | +| **scopes** | `string[]` | optional | OAuth scopes | +| **clientIdField** | `string` | optional | Client ID field name | +| **clientSecretField** | `string` | optional | Client secret field name | + +--- + +## OperationParameter + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Parameter name | +| **label** | `string` | ✅ | Parameter label | +| **description** | `string` | optional | Parameter description | +| **type** | `Enum<'string' \| 'number' \| 'boolean' \| 'array' \| 'object' \| 'date' \| 'file'>` | ✅ | Parameter type | +| **required** | `boolean` | optional | Required parameter | +| **default** | `any` | optional | Default value | +| **validation** | `Record` | optional | Validation rules | +| **dynamicOptions** | `string` | optional | Function to load dynamic options | + +--- + +## OperationType + +### Allowed Values + +* `read` +* `write` +* `delete` +* `search` +* `trigger` +* `action` + diff --git a/content/docs/references/automation/connector/AuthField.mdx b/content/docs/references/automation/connector/AuthField.mdx deleted file mode 100644 index 7b361e853..000000000 --- a/content/docs/references/automation/connector/AuthField.mdx +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: AuthField -description: AuthField Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Field name (snake_case) | -| **label** | `string` | ✅ | Field label | -| **type** | `Enum<'text' \| 'password' \| 'url' \| 'select'>` | optional | Field type | -| **description** | `string` | optional | Field description | -| **required** | `boolean` | optional | Required field | -| **default** | `string` | optional | Default value | -| **options** | `object[]` | optional | Select field options | -| **placeholder** | `string` | optional | Placeholder text | diff --git a/content/docs/references/automation/connector/Authentication.mdx b/content/docs/references/automation/connector/Authentication.mdx deleted file mode 100644 index 8f246e78f..000000000 --- a/content/docs/references/automation/connector/Authentication.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Authentication -description: Authentication Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `Enum<'none' \| 'apiKey' \| 'basic' \| 'bearer' \| 'oauth1' \| 'oauth2' \| 'custom'>` | ✅ | Authentication type | -| **fields** | `object[]` | optional | Authentication fields | -| **oauth2** | `object` | optional | OAuth 2.0 configuration | -| **test** | `object` | optional | Authentication test configuration | diff --git a/content/docs/references/automation/connector/AuthenticationType.mdx b/content/docs/references/automation/connector/AuthenticationType.mdx deleted file mode 100644 index 62060107e..000000000 --- a/content/docs/references/automation/connector/AuthenticationType.mdx +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: AuthenticationType -description: AuthenticationType Schema Reference ---- - -## Allowed Values - -* `none` -* `apiKey` -* `basic` -* `bearer` -* `oauth1` -* `oauth2` -* `custom` \ No newline at end of file diff --git a/content/docs/references/automation/connector/Connector.mdx b/content/docs/references/automation/connector/Connector.mdx deleted file mode 100644 index 9d46fc79c..000000000 --- a/content/docs/references/automation/connector/Connector.mdx +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: Connector -description: Connector Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Connector ID (snake_case) | -| **name** | `string` | ✅ | Connector name | -| **description** | `string` | optional | Connector description | -| **version** | `string` | optional | Connector version | -| **icon** | `string` | optional | Connector icon | -| **category** | `Enum<'crm' \| 'payment' \| 'communication' \| 'storage' \| 'analytics' \| 'database' \| 'marketing' \| 'accounting' \| 'hr' \| 'productivity' \| 'ecommerce' \| 'support' \| 'devtools' \| 'social' \| 'other'>` | ✅ | Connector category | -| **baseUrl** | `string` | optional | API base URL | -| **authentication** | `object` | ✅ | Authentication config | -| **operations** | `object[]` | optional | Connector operations | -| **triggers** | `object[]` | optional | Connector triggers | -| **rateLimit** | `object` | optional | Rate limiting | -| **author** | `string` | optional | Connector author | -| **documentation** | `string` | optional | Documentation URL | -| **homepage** | `string` | optional | Homepage URL | -| **license** | `string` | optional | License (SPDX identifier) | -| **tags** | `string[]` | optional | Connector tags | -| **verified** | `boolean` | optional | Verified connector | -| **metadata** | `Record` | optional | Custom metadata | diff --git a/content/docs/references/automation/connector/ConnectorCategory.mdx b/content/docs/references/automation/connector/ConnectorCategory.mdx deleted file mode 100644 index 93ad90f0c..000000000 --- a/content/docs/references/automation/connector/ConnectorCategory.mdx +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: ConnectorCategory -description: ConnectorCategory Schema Reference ---- - -## Allowed Values - -* `crm` -* `payment` -* `communication` -* `storage` -* `analytics` -* `database` -* `marketing` -* `accounting` -* `hr` -* `productivity` -* `ecommerce` -* `support` -* `devtools` -* `social` -* `other` \ No newline at end of file diff --git a/content/docs/references/automation/connector/ConnectorInstance.mdx b/content/docs/references/automation/connector/ConnectorInstance.mdx deleted file mode 100644 index 52799becd..000000000 --- a/content/docs/references/automation/connector/ConnectorInstance.mdx +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: ConnectorInstance -description: ConnectorInstance Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Instance ID | -| **connectorId** | `string` | ✅ | Connector ID | -| **name** | `string` | ✅ | Instance name | -| **description** | `string` | optional | Instance description | -| **credentials** | `Record` | ✅ | Encrypted credentials | -| **config** | `Record` | optional | Additional config | -| **active** | `boolean` | optional | Instance active status | -| **createdAt** | `string` | optional | Creation time | -| **lastTestedAt** | `string` | optional | Last test time | -| **testStatus** | `Enum<'unknown' \| 'success' \| 'failed'>` | optional | Connection test status | diff --git a/content/docs/references/automation/connector/ConnectorOperation.mdx b/content/docs/references/automation/connector/ConnectorOperation.mdx deleted file mode 100644 index d02607623..000000000 --- a/content/docs/references/automation/connector/ConnectorOperation.mdx +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: ConnectorOperation -description: ConnectorOperation Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Operation ID (snake_case) | -| **name** | `string` | ✅ | Operation name | -| **description** | `string` | optional | Operation description | -| **type** | `Enum<'read' \| 'write' \| 'delete' \| 'search' \| 'trigger' \| 'action'>` | ✅ | Operation type | -| **inputSchema** | `object[]` | optional | Input parameters | -| **outputSchema** | `Record` | optional | Output schema | -| **sampleOutput** | `any` | optional | Sample output | -| **supportsPagination** | `boolean` | optional | Supports pagination | -| **supportsFiltering** | `boolean` | optional | Supports filtering | diff --git a/content/docs/references/automation/connector/ConnectorTrigger.mdx b/content/docs/references/automation/connector/ConnectorTrigger.mdx deleted file mode 100644 index 0e8f44d49..000000000 --- a/content/docs/references/automation/connector/ConnectorTrigger.mdx +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: ConnectorTrigger -description: ConnectorTrigger Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Trigger ID (snake_case) | -| **name** | `string` | ✅ | Trigger name | -| **description** | `string` | optional | Trigger description | -| **type** | `Enum<'webhook' \| 'polling' \| 'stream'>` | ✅ | Trigger mechanism | -| **config** | `Record` | optional | Trigger configuration | -| **outputSchema** | `Record` | optional | Event payload schema | -| **pollingIntervalMs** | `integer` | optional | Polling interval in ms | diff --git a/content/docs/references/automation/connector/OAuth2Config.mdx b/content/docs/references/automation/connector/OAuth2Config.mdx deleted file mode 100644 index 56b9b7806..000000000 --- a/content/docs/references/automation/connector/OAuth2Config.mdx +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: OAuth2Config -description: OAuth2Config Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **authorizationUrl** | `string` | ✅ | Authorization endpoint URL | -| **tokenUrl** | `string` | ✅ | Token endpoint URL | -| **scopes** | `string[]` | optional | OAuth scopes | -| **clientIdField** | `string` | optional | Client ID field name | -| **clientSecretField** | `string` | optional | Client secret field name | diff --git a/content/docs/references/automation/connector/OperationParameter.mdx b/content/docs/references/automation/connector/OperationParameter.mdx deleted file mode 100644 index 57a928a2e..000000000 --- a/content/docs/references/automation/connector/OperationParameter.mdx +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: OperationParameter -description: OperationParameter Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Parameter name | -| **label** | `string` | ✅ | Parameter label | -| **description** | `string` | optional | Parameter description | -| **type** | `Enum<'string' \| 'number' \| 'boolean' \| 'array' \| 'object' \| 'date' \| 'file'>` | ✅ | Parameter type | -| **required** | `boolean` | optional | Required parameter | -| **default** | `any` | optional | Default value | -| **validation** | `Record` | optional | Validation rules | -| **dynamicOptions** | `string` | optional | Function to load dynamic options | diff --git a/content/docs/references/automation/connector/OperationType.mdx b/content/docs/references/automation/connector/OperationType.mdx deleted file mode 100644 index 4506104ca..000000000 --- a/content/docs/references/automation/connector/OperationType.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: OperationType -description: OperationType Schema Reference ---- - -## Allowed Values - -* `read` -* `write` -* `delete` -* `search` -* `trigger` -* `action` \ No newline at end of file diff --git a/content/docs/references/automation/connector/meta.json b/content/docs/references/automation/connector/meta.json deleted file mode 100644 index b89ecdbeb..000000000 --- a/content/docs/references/automation/connector/meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "title": "Connector" -} \ No newline at end of file diff --git a/content/docs/references/automation/etl.mdx b/content/docs/references/automation/etl.mdx new file mode 100644 index 000000000..f5bb7c6aa --- /dev/null +++ b/content/docs/references/automation/etl.mdx @@ -0,0 +1,156 @@ +--- +title: Etl +description: Etl protocol schemas +--- + +# Etl + + +**Source:** `packages/spec/src/automation/etl.zod.ts` + + +## TypeScript Usage + +```typescript +import { ETLDestinationSchema, ETLEndpointTypeSchema, ETLPipelineSchema, ETLPipelineRunSchema, ETLRunStatusSchema, ETLSourceSchema, ETLSyncModeSchema, ETLTransformationSchema, ETLTransformationTypeSchema } from '@objectstack/spec/automation'; +import type { ETLDestination, ETLEndpointType, ETLPipeline, ETLPipelineRun, ETLRunStatus, ETLSource, ETLSyncMode, ETLTransformation, ETLTransformationType } from '@objectstack/spec/automation'; + +// Validate data +const result = ETLDestinationSchema.parse(data); +``` + +--- + +## ETLDestination + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **type** | `Enum<'database' \| 'api' \| 'file' \| 'stream' \| 'object' \| 'warehouse' \| 'storage' \| 'spreadsheet'>` | ✅ | Destination type | +| **connector** | `string` | optional | Connector ID | +| **config** | `Record` | ✅ | Destination configuration | +| **writeMode** | `Enum<'append' \| 'overwrite' \| 'upsert' \| 'merge'>` | optional | How to write data | +| **primaryKey** | `string[]` | optional | Primary key fields | + +--- + +## ETLEndpointType + +### Allowed Values + +* `database` +* `api` +* `file` +* `stream` +* `object` +* `warehouse` +* `storage` +* `spreadsheet` + +--- + +## ETLPipeline + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Pipeline identifier (snake_case) | +| **label** | `string` | optional | Pipeline display name | +| **description** | `string` | optional | Pipeline description | +| **source** | `object` | ✅ | Data source | +| **destination** | `object` | ✅ | Data destination | +| **transformations** | `object[]` | optional | Transformation pipeline | +| **syncMode** | `Enum<'full' \| 'incremental' \| 'cdc'>` | optional | Sync mode | +| **schedule** | `string` | optional | Cron schedule expression | +| **enabled** | `boolean` | optional | Pipeline enabled status | +| **retry** | `object` | optional | Retry configuration | +| **notifications** | `object` | optional | Notification settings | +| **tags** | `string[]` | optional | Pipeline tags | +| **metadata** | `Record` | optional | Custom metadata | + +--- + +## ETLPipelineRun + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | ✅ | Run identifier | +| **pipelineName** | `string` | ✅ | Pipeline name | +| **status** | `Enum<'pending' \| 'running' \| 'succeeded' \| 'failed' \| 'cancelled' \| 'timeout'>` | ✅ | Run status | +| **startedAt** | `string` | ✅ | Start time | +| **completedAt** | `string` | optional | Completion time | +| **durationMs** | `number` | optional | Duration in ms | +| **stats** | `object` | optional | Run statistics | +| **error** | `object` | optional | Error information | +| **logs** | `string[]` | optional | Execution logs | + +--- + +## ETLRunStatus + +### Allowed Values + +* `pending` +* `running` +* `succeeded` +* `failed` +* `cancelled` +* `timeout` + +--- + +## ETLSource + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **type** | `Enum<'database' \| 'api' \| 'file' \| 'stream' \| 'object' \| 'warehouse' \| 'storage' \| 'spreadsheet'>` | ✅ | Source type | +| **connector** | `string` | optional | Connector ID | +| **config** | `Record` | ✅ | Source configuration | +| **incremental** | `object` | optional | Incremental extraction config | + +--- + +## ETLSyncMode + +### Allowed Values + +* `full` +* `incremental` +* `cdc` + +--- + +## ETLTransformation + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | optional | Transformation name | +| **type** | `Enum<'map' \| 'filter' \| 'aggregate' \| 'join' \| 'script' \| 'lookup' \| 'split' \| 'merge' \| 'normalize' \| 'deduplicate'>` | ✅ | Transformation type | +| **config** | `Record` | ✅ | Transformation config | +| **continueOnError** | `boolean` | optional | Continue on error | + +--- + +## ETLTransformationType + +### Allowed Values + +* `map` +* `filter` +* `aggregate` +* `join` +* `script` +* `lookup` +* `split` +* `merge` +* `normalize` +* `deduplicate` + diff --git a/content/docs/references/automation/etl/ETLDestination.mdx b/content/docs/references/automation/etl/ETLDestination.mdx deleted file mode 100644 index da14d10d1..000000000 --- a/content/docs/references/automation/etl/ETLDestination.mdx +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: ETLDestination -description: ETLDestination Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `Enum<'database' \| 'api' \| 'file' \| 'stream' \| 'object' \| 'warehouse' \| 'storage' \| 'spreadsheet'>` | ✅ | Destination type | -| **connector** | `string` | optional | Connector ID | -| **config** | `Record` | ✅ | Destination configuration | -| **writeMode** | `Enum<'append' \| 'overwrite' \| 'upsert' \| 'merge'>` | optional | How to write data | -| **primaryKey** | `string[]` | optional | Primary key fields | diff --git a/content/docs/references/automation/etl/ETLEndpointType.mdx b/content/docs/references/automation/etl/ETLEndpointType.mdx deleted file mode 100644 index e085179cd..000000000 --- a/content/docs/references/automation/etl/ETLEndpointType.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: ETLEndpointType -description: ETLEndpointType Schema Reference ---- - -## Allowed Values - -* `database` -* `api` -* `file` -* `stream` -* `object` -* `warehouse` -* `storage` -* `spreadsheet` \ No newline at end of file diff --git a/content/docs/references/automation/etl/ETLPipeline.mdx b/content/docs/references/automation/etl/ETLPipeline.mdx deleted file mode 100644 index 3bf4c3c79..000000000 --- a/content/docs/references/automation/etl/ETLPipeline.mdx +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: ETLPipeline -description: ETLPipeline Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Pipeline identifier (snake_case) | -| **label** | `string` | optional | Pipeline display name | -| **description** | `string` | optional | Pipeline description | -| **source** | `object` | ✅ | Data source | -| **destination** | `object` | ✅ | Data destination | -| **transformations** | `object[]` | optional | Transformation pipeline | -| **syncMode** | `Enum<'full' \| 'incremental' \| 'cdc'>` | optional | Sync mode | -| **schedule** | `string` | optional | Cron schedule expression | -| **enabled** | `boolean` | optional | Pipeline enabled status | -| **retry** | `object` | optional | Retry configuration | -| **notifications** | `object` | optional | Notification settings | -| **tags** | `string[]` | optional | Pipeline tags | -| **metadata** | `Record` | optional | Custom metadata | diff --git a/content/docs/references/automation/etl/ETLPipelineRun.mdx b/content/docs/references/automation/etl/ETLPipelineRun.mdx deleted file mode 100644 index 50d06bde7..000000000 --- a/content/docs/references/automation/etl/ETLPipelineRun.mdx +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: ETLPipelineRun -description: ETLPipelineRun Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Run identifier | -| **pipelineName** | `string` | ✅ | Pipeline name | -| **status** | `Enum<'pending' \| 'running' \| 'succeeded' \| 'failed' \| 'cancelled' \| 'timeout'>` | ✅ | Run status | -| **startedAt** | `string` | ✅ | Start time | -| **completedAt** | `string` | optional | Completion time | -| **durationMs** | `number` | optional | Duration in ms | -| **stats** | `object` | optional | Run statistics | -| **error** | `object` | optional | Error information | -| **logs** | `string[]` | optional | Execution logs | diff --git a/content/docs/references/automation/etl/ETLRunStatus.mdx b/content/docs/references/automation/etl/ETLRunStatus.mdx deleted file mode 100644 index a5c018d1e..000000000 --- a/content/docs/references/automation/etl/ETLRunStatus.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: ETLRunStatus -description: ETLRunStatus Schema Reference ---- - -## Allowed Values - -* `pending` -* `running` -* `succeeded` -* `failed` -* `cancelled` -* `timeout` \ No newline at end of file diff --git a/content/docs/references/automation/etl/ETLSource.mdx b/content/docs/references/automation/etl/ETLSource.mdx deleted file mode 100644 index dbdd9c44e..000000000 --- a/content/docs/references/automation/etl/ETLSource.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: ETLSource -description: ETLSource Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `Enum<'database' \| 'api' \| 'file' \| 'stream' \| 'object' \| 'warehouse' \| 'storage' \| 'spreadsheet'>` | ✅ | Source type | -| **connector** | `string` | optional | Connector ID | -| **config** | `Record` | ✅ | Source configuration | -| **incremental** | `object` | optional | Incremental extraction config | diff --git a/content/docs/references/automation/etl/ETLSyncMode.mdx b/content/docs/references/automation/etl/ETLSyncMode.mdx deleted file mode 100644 index 7f2c49c69..000000000 --- a/content/docs/references/automation/etl/ETLSyncMode.mdx +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: ETLSyncMode -description: ETLSyncMode Schema Reference ---- - -## Allowed Values - -* `full` -* `incremental` -* `cdc` \ No newline at end of file diff --git a/content/docs/references/automation/etl/ETLTransformation.mdx b/content/docs/references/automation/etl/ETLTransformation.mdx deleted file mode 100644 index 5cdf487f7..000000000 --- a/content/docs/references/automation/etl/ETLTransformation.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: ETLTransformation -description: ETLTransformation Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | optional | Transformation name | -| **type** | `Enum<'map' \| 'filter' \| 'aggregate' \| 'join' \| 'script' \| 'lookup' \| 'split' \| 'merge' \| 'normalize' \| 'deduplicate'>` | ✅ | Transformation type | -| **config** | `Record` | ✅ | Transformation config | -| **continueOnError** | `boolean` | optional | Continue on error | diff --git a/content/docs/references/automation/etl/ETLTransformationType.mdx b/content/docs/references/automation/etl/ETLTransformationType.mdx deleted file mode 100644 index 47be46d4f..000000000 --- a/content/docs/references/automation/etl/ETLTransformationType.mdx +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: ETLTransformationType -description: ETLTransformationType Schema Reference ---- - -## Allowed Values - -* `map` -* `filter` -* `aggregate` -* `join` -* `script` -* `lookup` -* `split` -* `merge` -* `normalize` -* `deduplicate` \ No newline at end of file diff --git a/content/docs/references/automation/etl/meta.json b/content/docs/references/automation/etl/meta.json deleted file mode 100644 index d3fd031f1..000000000 --- a/content/docs/references/automation/etl/meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "title": "Etl" -} \ No newline at end of file diff --git a/content/docs/references/automation/flow.mdx b/content/docs/references/automation/flow.mdx new file mode 100644 index 000000000..8adab3d5f --- /dev/null +++ b/content/docs/references/automation/flow.mdx @@ -0,0 +1,104 @@ +--- +title: Flow +description: Flow protocol schemas +--- + +# Flow + + +**Source:** `packages/spec/src/automation/flow.zod.ts` + + +## TypeScript Usage + +```typescript +import { FlowSchema, FlowEdgeSchema, FlowNodeSchema, FlowNodeActionSchema, FlowVariableSchema } from '@objectstack/spec/automation'; +import type { Flow, FlowEdge, FlowNode, FlowNodeAction, FlowVariable } from '@objectstack/spec/automation'; + +// Validate data +const result = FlowSchema.parse(data); +``` + +--- + +## Flow + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Machine name | +| **label** | `string` | ✅ | Flow label | +| **description** | `string` | optional | | +| **version** | `integer` | optional | Version number | +| **status** | `Enum<'draft' \| 'active' \| 'obsolete' \| 'invalid'>` | optional | Deployment status | +| **template** | `boolean` | optional | Is logic template (Subflow) | +| **type** | `Enum<'autolaunched' \| 'record_change' \| 'schedule' \| 'screen' \| 'api'>` | ✅ | Flow type | +| **variables** | `object[]` | optional | Flow variables | +| **nodes** | `object[]` | ✅ | Flow nodes | +| **edges** | `object[]` | ✅ | Flow connections | +| **active** | `boolean` | optional | Is active (Deprecated: use status) | +| **runAs** | `Enum<'system' \| 'user'>` | optional | Execution context | + +--- + +## FlowEdge + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | ✅ | Edge unique ID | +| **source** | `string` | ✅ | Source Node ID | +| **target** | `string` | ✅ | Target Node ID | +| **condition** | `string` | optional | Expression returning boolean used for branching | +| **type** | `Enum<'default' \| 'fault'>` | optional | Connection type: Standard (Success) or Fault (Error) path | +| **label** | `string` | optional | Label on the connector | + +--- + +## FlowNode + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | ✅ | Node unique ID | +| **type** | `Enum<'start' \| 'end' \| 'decision' \| 'assignment' \| 'loop' \| 'create_record' \| 'update_record' \| 'delete_record' \| 'get_record' \| 'http_request' \| 'script' \| 'wait' \| 'subflow'>` | ✅ | Action type | +| **label** | `string` | ✅ | Node label | +| **config** | `Record` | optional | Node configuration | +| **position** | `object` | optional | | + +--- + +## FlowNodeAction + +### Allowed Values + +* `start` +* `end` +* `decision` +* `assignment` +* `loop` +* `create_record` +* `update_record` +* `delete_record` +* `get_record` +* `http_request` +* `script` +* `wait` +* `subflow` + +--- + +## FlowVariable + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Variable name | +| **type** | `string` | ✅ | Data type (text, number, boolean, object, list) | +| **isInput** | `boolean` | optional | Is input parameter | +| **isOutput** | `boolean` | optional | Is output parameter | + diff --git a/content/docs/references/automation/flow/Flow.mdx b/content/docs/references/automation/flow/Flow.mdx deleted file mode 100644 index 188f7ebe6..000000000 --- a/content/docs/references/automation/flow/Flow.mdx +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: Flow -description: Flow Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Machine name | -| **label** | `string` | ✅ | Flow label | -| **description** | `string` | optional | | -| **version** | `integer` | optional | Version number | -| **status** | `Enum<'draft' \| 'active' \| 'obsolete' \| 'invalid'>` | optional | Deployment status | -| **template** | `boolean` | optional | Is logic template (Subflow) | -| **type** | `Enum<'autolaunched' \| 'record_change' \| 'schedule' \| 'screen' \| 'api'>` | ✅ | Flow type | -| **variables** | `object[]` | optional | Flow variables | -| **nodes** | `object[]` | ✅ | Flow nodes | -| **edges** | `object[]` | ✅ | Flow connections | -| **active** | `boolean` | optional | Is active (Deprecated: use status) | -| **runAs** | `Enum<'system' \| 'user'>` | optional | Execution context | diff --git a/content/docs/references/automation/flow/FlowEdge.mdx b/content/docs/references/automation/flow/FlowEdge.mdx deleted file mode 100644 index 5a3fe6e0c..000000000 --- a/content/docs/references/automation/flow/FlowEdge.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: FlowEdge -description: FlowEdge Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Edge unique ID | -| **source** | `string` | ✅ | Source Node ID | -| **target** | `string` | ✅ | Target Node ID | -| **condition** | `string` | optional | Expression returning boolean used for branching | -| **type** | `Enum<'default' \| 'fault'>` | optional | Connection type: Standard (Success) or Fault (Error) path | -| **label** | `string` | optional | Label on the connector | diff --git a/content/docs/references/automation/flow/FlowNode.mdx b/content/docs/references/automation/flow/FlowNode.mdx deleted file mode 100644 index d36e3a88f..000000000 --- a/content/docs/references/automation/flow/FlowNode.mdx +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: FlowNode -description: FlowNode Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Node unique ID | -| **type** | `Enum<'start' \| 'end' \| 'decision' \| 'assignment' \| 'loop' \| 'create_record' \| 'update_record' \| 'delete_record' \| 'get_record' \| 'http_request' \| 'script' \| 'wait' \| 'subflow'>` | ✅ | Action type | -| **label** | `string` | ✅ | Node label | -| **config** | `Record` | optional | Node configuration | -| **position** | `object` | optional | | diff --git a/content/docs/references/automation/flow/FlowNodeAction.mdx b/content/docs/references/automation/flow/FlowNodeAction.mdx deleted file mode 100644 index 0d0a054ef..000000000 --- a/content/docs/references/automation/flow/FlowNodeAction.mdx +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: FlowNodeAction -description: FlowNodeAction Schema Reference ---- - -## Allowed Values - -* `start` -* `end` -* `decision` -* `assignment` -* `loop` -* `create_record` -* `update_record` -* `delete_record` -* `get_record` -* `http_request` -* `script` -* `wait` -* `subflow` \ No newline at end of file diff --git a/content/docs/references/automation/flow/FlowVariable.mdx b/content/docs/references/automation/flow/FlowVariable.mdx deleted file mode 100644 index 82f28b8b8..000000000 --- a/content/docs/references/automation/flow/FlowVariable.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: FlowVariable -description: FlowVariable Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Variable name | -| **type** | `string` | ✅ | Data type (text, number, boolean, object, list) | -| **isInput** | `boolean` | optional | Is input parameter | -| **isOutput** | `boolean` | optional | Is output parameter | diff --git a/content/docs/references/automation/flow/meta.json b/content/docs/references/automation/flow/meta.json deleted file mode 100644 index 51349f2a7..000000000 --- a/content/docs/references/automation/flow/meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "title": "Flow" -} \ No newline at end of file diff --git a/content/docs/references/automation/index.mdx b/content/docs/references/automation/index.mdx new file mode 100644 index 000000000..c071ba213 --- /dev/null +++ b/content/docs/references/automation/index.mdx @@ -0,0 +1,19 @@ +--- +title: Automation Protocol Overview +description: Complete reference for all automation protocol schemas +--- + +# Automation Protocol + +This section contains all protocol schemas for the automation layer of ObjectStack. + + + + + + + + + + + diff --git a/content/docs/references/automation/mapping.mdx b/content/docs/references/automation/mapping.mdx new file mode 100644 index 000000000..b20c29daf --- /dev/null +++ b/content/docs/references/automation/mapping.mdx @@ -0,0 +1,35 @@ +--- +title: Mapping +description: Mapping protocol schemas +--- + +# Mapping + + +**Source:** `packages/spec/src/automation/mapping.zod.ts` + + +## TypeScript Usage + +```typescript +import { FieldMappingSchema } from '@objectstack/spec/automation'; +import type { FieldMapping } from '@objectstack/spec/automation'; + +// Validate data +const result = FieldMappingSchema.parse(data); +``` + +--- + +## FieldMapping + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **sourceField** | `string` | ✅ | Source field name | +| **destinationField** | `string` | ✅ | Destination field name | +| **transform** | `string` | optional | Transformation formula | +| **default** | `any` | optional | Default value | +| **syncNull** | `boolean` | optional | Sync null values | + diff --git a/content/docs/references/automation/mapping/FieldMapping.mdx b/content/docs/references/automation/mapping/FieldMapping.mdx deleted file mode 100644 index e53d8f039..000000000 --- a/content/docs/references/automation/mapping/FieldMapping.mdx +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: FieldMapping -description: FieldMapping Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **sourceField** | `string` | ✅ | Source field name | -| **destinationField** | `string` | ✅ | Destination field name | -| **transform** | `string` | optional | Transformation formula | -| **default** | `any` | optional | Default value | -| **syncNull** | `boolean` | optional | Sync null values | diff --git a/content/docs/references/automation/sync.mdx b/content/docs/references/automation/sync.mdx new file mode 100644 index 000000000..89a4a0762 --- /dev/null +++ b/content/docs/references/automation/sync.mdx @@ -0,0 +1,141 @@ +--- +title: Sync +description: Sync protocol schemas +--- + +# Sync + + +**Source:** `packages/spec/src/automation/sync.zod.ts` + + +## TypeScript Usage + +```typescript +import { ConflictResolutionSchema, DataDestinationConfigSchema, DataSourceConfigSchema, DataSyncConfigSchema, SyncDirectionSchema, SyncExecutionResultSchema, SyncExecutionStatusSchema, SyncModeSchema } from '@objectstack/spec/automation'; +import type { ConflictResolution, DataDestinationConfig, DataSourceConfig, DataSyncConfig, SyncDirection, SyncExecutionResult, SyncExecutionStatus, SyncMode } from '@objectstack/spec/automation'; + +// Validate data +const result = ConflictResolutionSchema.parse(data); +``` + +--- + +## ConflictResolution + +### Allowed Values + +* `source_wins` +* `destination_wins` +* `latest_wins` +* `manual` +* `merge` + +--- + +## DataDestinationConfig + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **object** | `string` | optional | ObjectStack object name | +| **connectorInstanceId** | `string` | optional | Connector instance ID | +| **operation** | `Enum<'insert' \| 'update' \| 'upsert' \| 'delete' \| 'sync'>` | ✅ | Sync operation | +| **mapping** | `Record \| object[]` | optional | Field mappings | +| **externalResource** | `string` | optional | External resource ID | +| **matchKey** | `string[]` | optional | Match key fields | + +--- + +## DataSourceConfig + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **object** | `string` | optional | ObjectStack object name | +| **filters** | `any` | optional | Filter conditions | +| **fields** | `string[]` | optional | Fields to sync | +| **connectorInstanceId** | `string` | optional | Connector instance ID | +| **externalResource** | `string` | optional | External resource ID | + +--- + +## DataSyncConfig + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Sync configuration name (snake_case) | +| **label** | `string` | optional | Sync display name | +| **description** | `string` | optional | Sync description | +| **source** | `object` | ✅ | Data source | +| **destination** | `object` | ✅ | Data destination | +| **direction** | `Enum<'push' \| 'pull' \| 'bidirectional'>` | optional | Sync direction | +| **syncMode** | `Enum<'full' \| 'incremental' \| 'realtime'>` | optional | Sync mode | +| **conflictResolution** | `Enum<'source_wins' \| 'destination_wins' \| 'latest_wins' \| 'manual' \| 'merge'>` | optional | Conflict resolution | +| **schedule** | `string` | optional | Cron schedule | +| **enabled** | `boolean` | optional | Sync enabled | +| **changeTrackingField** | `string` | optional | Field for change tracking | +| **batchSize** | `integer` | optional | Batch size for processing | +| **retry** | `object` | optional | Retry configuration | +| **validation** | `object` | optional | Validation rules | +| **errorHandling** | `object` | optional | Error handling | +| **optimization** | `object` | optional | Performance optimization | +| **audit** | `object` | optional | Audit configuration | +| **tags** | `string[]` | optional | Sync tags | +| **metadata** | `Record` | optional | Custom metadata | + +--- + +## SyncDirection + +### Allowed Values + +* `push` +* `pull` +* `bidirectional` + +--- + +## SyncExecutionResult + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | ✅ | Execution ID | +| **syncName** | `string` | ✅ | Sync name | +| **status** | `Enum<'pending' \| 'running' \| 'completed' \| 'partial' \| 'failed' \| 'cancelled'>` | ✅ | Execution status | +| **startedAt** | `string` | ✅ | Start time | +| **completedAt** | `string` | optional | Completion time | +| **durationMs** | `number` | optional | Duration in ms | +| **stats** | `object` | optional | Execution statistics | +| **errors** | `object[]` | optional | Errors | +| **logs** | `string[]` | optional | Execution logs | + +--- + +## SyncExecutionStatus + +### Allowed Values + +* `pending` +* `running` +* `completed` +* `partial` +* `failed` +* `cancelled` + +--- + +## SyncMode + +### Allowed Values + +* `full` +* `incremental` +* `realtime` + diff --git a/content/docs/references/automation/sync/ConflictResolution.mdx b/content/docs/references/automation/sync/ConflictResolution.mdx deleted file mode 100644 index 623a5aeb9..000000000 --- a/content/docs/references/automation/sync/ConflictResolution.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: ConflictResolution -description: ConflictResolution Schema Reference ---- - -## Allowed Values - -* `source_wins` -* `destination_wins` -* `latest_wins` -* `manual` -* `merge` \ No newline at end of file diff --git a/content/docs/references/automation/sync/DataDestinationConfig.mdx b/content/docs/references/automation/sync/DataDestinationConfig.mdx deleted file mode 100644 index 59bf93ddf..000000000 --- a/content/docs/references/automation/sync/DataDestinationConfig.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: DataDestinationConfig -description: DataDestinationConfig Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **object** | `string` | optional | ObjectStack object name | -| **connectorInstanceId** | `string` | optional | Connector instance ID | -| **operation** | `Enum<'insert' \| 'update' \| 'upsert' \| 'delete' \| 'sync'>` | ✅ | Sync operation | -| **mapping** | `Record \| object[]` | optional | Field mappings | -| **externalResource** | `string` | optional | External resource ID | -| **matchKey** | `string[]` | optional | Match key fields | diff --git a/content/docs/references/automation/sync/DataSourceConfig.mdx b/content/docs/references/automation/sync/DataSourceConfig.mdx deleted file mode 100644 index c0d6a79ba..000000000 --- a/content/docs/references/automation/sync/DataSourceConfig.mdx +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: DataSourceConfig -description: DataSourceConfig Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **object** | `string` | optional | ObjectStack object name | -| **filters** | `any` | optional | Filter conditions | -| **fields** | `string[]` | optional | Fields to sync | -| **connectorInstanceId** | `string` | optional | Connector instance ID | -| **externalResource** | `string` | optional | External resource ID | diff --git a/content/docs/references/automation/sync/DataSyncConfig.mdx b/content/docs/references/automation/sync/DataSyncConfig.mdx deleted file mode 100644 index aaee284da..000000000 --- a/content/docs/references/automation/sync/DataSyncConfig.mdx +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: DataSyncConfig -description: DataSyncConfig Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Sync configuration name (snake_case) | -| **label** | `string` | optional | Sync display name | -| **description** | `string` | optional | Sync description | -| **source** | `object` | ✅ | Data source | -| **destination** | `object` | ✅ | Data destination | -| **direction** | `Enum<'push' \| 'pull' \| 'bidirectional'>` | optional | Sync direction | -| **syncMode** | `Enum<'full' \| 'incremental' \| 'realtime'>` | optional | Sync mode | -| **conflictResolution** | `Enum<'source_wins' \| 'destination_wins' \| 'latest_wins' \| 'manual' \| 'merge'>` | optional | Conflict resolution | -| **schedule** | `string` | optional | Cron schedule | -| **enabled** | `boolean` | optional | Sync enabled | -| **changeTrackingField** | `string` | optional | Field for change tracking | -| **batchSize** | `integer` | optional | Batch size for processing | -| **retry** | `object` | optional | Retry configuration | -| **validation** | `object` | optional | Validation rules | -| **errorHandling** | `object` | optional | Error handling | -| **optimization** | `object` | optional | Performance optimization | -| **audit** | `object` | optional | Audit configuration | -| **tags** | `string[]` | optional | Sync tags | -| **metadata** | `Record` | optional | Custom metadata | diff --git a/content/docs/references/automation/sync/SyncDirection.mdx b/content/docs/references/automation/sync/SyncDirection.mdx deleted file mode 100644 index 4d65f05ca..000000000 --- a/content/docs/references/automation/sync/SyncDirection.mdx +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: SyncDirection -description: SyncDirection Schema Reference ---- - -## Allowed Values - -* `push` -* `pull` -* `bidirectional` \ No newline at end of file diff --git a/content/docs/references/automation/sync/SyncExecutionResult.mdx b/content/docs/references/automation/sync/SyncExecutionResult.mdx deleted file mode 100644 index 388e3794a..000000000 --- a/content/docs/references/automation/sync/SyncExecutionResult.mdx +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: SyncExecutionResult -description: SyncExecutionResult Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Execution ID | -| **syncName** | `string` | ✅ | Sync name | -| **status** | `Enum<'pending' \| 'running' \| 'completed' \| 'partial' \| 'failed' \| 'cancelled'>` | ✅ | Execution status | -| **startedAt** | `string` | ✅ | Start time | -| **completedAt** | `string` | optional | Completion time | -| **durationMs** | `number` | optional | Duration in ms | -| **stats** | `object` | optional | Execution statistics | -| **errors** | `object[]` | optional | Errors | -| **logs** | `string[]` | optional | Execution logs | diff --git a/content/docs/references/automation/sync/SyncExecutionStatus.mdx b/content/docs/references/automation/sync/SyncExecutionStatus.mdx deleted file mode 100644 index be4b86047..000000000 --- a/content/docs/references/automation/sync/SyncExecutionStatus.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: SyncExecutionStatus -description: SyncExecutionStatus Schema Reference ---- - -## Allowed Values - -* `pending` -* `running` -* `completed` -* `partial` -* `failed` -* `cancelled` \ No newline at end of file diff --git a/content/docs/references/automation/sync/SyncMode.mdx b/content/docs/references/automation/sync/SyncMode.mdx deleted file mode 100644 index 746d60c3e..000000000 --- a/content/docs/references/automation/sync/SyncMode.mdx +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: SyncMode -description: SyncMode Schema Reference ---- - -## Allowed Values - -* `full` -* `incremental` -* `realtime` \ No newline at end of file diff --git a/content/docs/references/automation/sync/meta.json b/content/docs/references/automation/sync/meta.json deleted file mode 100644 index 770697c20..000000000 --- a/content/docs/references/automation/sync/meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "title": "Sync" -} \ No newline at end of file diff --git a/content/docs/references/automation/webhook.mdx b/content/docs/references/automation/webhook.mdx new file mode 100644 index 000000000..b157665f8 --- /dev/null +++ b/content/docs/references/automation/webhook.mdx @@ -0,0 +1,69 @@ +--- +title: Webhook +description: Webhook protocol schemas +--- + +# Webhook + + +**Source:** `packages/spec/src/automation/webhook.zod.ts` + + +## TypeScript Usage + +```typescript +import { WebhookSchema, WebhookReceiverSchema, WebhookTriggerTypeSchema } from '@objectstack/spec/automation'; +import type { Webhook, WebhookReceiver, WebhookTriggerType } from '@objectstack/spec/automation'; + +// Validate data +const result = WebhookSchema.parse(data); +``` + +--- + +## Webhook + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Webhook unique name (lowercase snake_case) | +| **label** | `string` | optional | | +| **object** | `string` | ✅ | Object to listen to | +| **triggers** | `Enum<'create' \| 'update' \| 'delete' \| 'undelete' \| 'api'>[]` | ✅ | Events that trigger execution | +| **url** | `string` | ✅ | External URL payload | +| **method** | `Enum<'POST' \| 'PUT' \| 'GET'>` | optional | | +| **secret** | `string` | optional | Signing secret (HMAC) | +| **headers** | `Record` | optional | Custom headers (Auth) | +| **payloadFields** | `string[]` | optional | Fields to include. Empty = All | +| **includeSession** | `boolean` | optional | Include user session info | +| **retryCount** | `number` | optional | | +| **isActive** | `boolean` | optional | | + +--- + +## WebhookReceiver + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Webhook receiver unique name (lowercase snake_case) | +| **path** | `string` | ✅ | URL Path (e.g. /webhooks/stripe) | +| **verificationType** | `Enum<'none' \| 'header_token' \| 'hmac' \| 'ip_whitelist'>` | optional | | +| **verificationParams** | `object` | optional | | +| **action** | `Enum<'trigger_flow' \| 'script' \| 'upsert_record'>` | optional | | +| **target** | `string` | ✅ | Flow ID or Script name | + +--- + +## WebhookTriggerType + +### Allowed Values + +* `create` +* `update` +* `delete` +* `undelete` +* `api` + diff --git a/content/docs/references/automation/webhook/Webhook.mdx b/content/docs/references/automation/webhook/Webhook.mdx deleted file mode 100644 index 0c4feb308..000000000 --- a/content/docs/references/automation/webhook/Webhook.mdx +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: Webhook -description: Webhook Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Webhook unique name (lowercase snake_case) | -| **label** | `string` | optional | | -| **object** | `string` | ✅ | Object to listen to | -| **triggers** | `Enum<'create' \| 'update' \| 'delete' \| 'undelete' \| 'api'>[]` | ✅ | Events that trigger execution | -| **url** | `string` | ✅ | External URL payload | -| **method** | `Enum<'POST' \| 'PUT' \| 'GET'>` | optional | | -| **secret** | `string` | optional | Signing secret (HMAC) | -| **headers** | `Record` | optional | Custom headers (Auth) | -| **payloadFields** | `string[]` | optional | Fields to include. Empty = All | -| **includeSession** | `boolean` | optional | Include user session info | -| **retryCount** | `number` | optional | | -| **isActive** | `boolean` | optional | | diff --git a/content/docs/references/automation/webhook/WebhookReceiver.mdx b/content/docs/references/automation/webhook/WebhookReceiver.mdx deleted file mode 100644 index 1de662065..000000000 --- a/content/docs/references/automation/webhook/WebhookReceiver.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: WebhookReceiver -description: WebhookReceiver Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Webhook receiver unique name (lowercase snake_case) | -| **path** | `string` | ✅ | URL Path (e.g. /webhooks/stripe) | -| **verificationType** | `Enum<'none' \| 'header_token' \| 'hmac' \| 'ip_whitelist'>` | optional | | -| **verificationParams** | `object` | optional | | -| **action** | `Enum<'trigger_flow' \| 'script' \| 'upsert_record'>` | optional | | -| **target** | `string` | ✅ | Flow ID or Script name | diff --git a/content/docs/references/automation/webhook/WebhookTriggerType.mdx b/content/docs/references/automation/webhook/WebhookTriggerType.mdx deleted file mode 100644 index 18c38830b..000000000 --- a/content/docs/references/automation/webhook/WebhookTriggerType.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: WebhookTriggerType -description: WebhookTriggerType Schema Reference ---- - -## Allowed Values - -* `create` -* `update` -* `delete` -* `undelete` -* `api` \ No newline at end of file diff --git a/content/docs/references/automation/webhook/meta.json b/content/docs/references/automation/webhook/meta.json deleted file mode 100644 index 790fdad82..000000000 --- a/content/docs/references/automation/webhook/meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "title": "Webhook" -} \ No newline at end of file diff --git a/content/docs/references/automation/workflow.mdx b/content/docs/references/automation/workflow.mdx new file mode 100644 index 000000000..38fee5ddd --- /dev/null +++ b/content/docs/references/automation/workflow.mdx @@ -0,0 +1,227 @@ +--- +title: Workflow +description: Workflow protocol schemas +--- + +# Workflow + + +**Source:** `packages/spec/src/automation/workflow.zod.ts` + + +## TypeScript Usage + +```typescript +import { CustomScriptActionSchema, EmailAlertActionSchema, FieldUpdateActionSchema, HttpCallActionSchema, PushNotificationActionSchema, SlackMessageActionSchema, SmsNotificationActionSchema, TaskCreationActionSchema, TeamsMessageActionSchema, TimeTriggerSchema, WebhookTriggerActionSchema, WorkflowActionSchema, WorkflowRuleSchema, WorkflowTriggerTypeSchema } from '@objectstack/spec/automation'; +import type { CustomScriptAction, EmailAlertAction, FieldUpdateAction, HttpCallAction, PushNotificationAction, SlackMessageAction, SmsNotificationAction, TaskCreationAction, TeamsMessageAction, TimeTrigger, WebhookTriggerAction, WorkflowAction, WorkflowRule, WorkflowTriggerType } from '@objectstack/spec/automation'; + +// Validate data +const result = CustomScriptActionSchema.parse(data); +``` + +--- + +## CustomScriptAction + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Action name | +| **type** | `string` | ✅ | | +| **language** | `Enum<'javascript' \| 'typescript' \| 'python'>` | optional | Script language | +| **code** | `string` | ✅ | Script code to execute | +| **timeout** | `number` | optional | Execution timeout in milliseconds | +| **context** | `Record` | optional | Additional context variables | + +--- + +## EmailAlertAction + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Action name | +| **type** | `string` | ✅ | | +| **template** | `string` | ✅ | Email template ID/DevName | +| **recipients** | `string[]` | ✅ | List of recipient emails or user IDs | + +--- + +## FieldUpdateAction + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Action name | +| **type** | `string` | ✅ | | +| **field** | `string` | ✅ | Field to update | +| **value** | `any` | optional | Value or Formula to set | + +--- + +## HttpCallAction + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Action name | +| **type** | `string` | ✅ | | +| **url** | `string` | ✅ | Target URL | +| **method** | `Enum<'GET' \| 'POST' \| 'PUT' \| 'PATCH' \| 'DELETE'>` | ✅ | HTTP method | +| **headers** | `Record` | optional | Request headers | +| **body** | `any` | optional | Request body (object/string) | +| **authentication** | `object` | optional | Authentication configuration | +| **timeout** | `number` | optional | Request timeout in milliseconds | + +--- + +## PushNotificationAction + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Action name | +| **type** | `string` | ✅ | | +| **title** | `string` | ✅ | Notification title | +| **body** | `string` | ✅ | Notification body text | +| **recipients** | `string[]` | ✅ | User IDs or device tokens | +| **data** | `Record` | optional | Additional data payload | +| **badge** | `number` | optional | Badge count (iOS) | +| **sound** | `string` | optional | Notification sound | +| **clickAction** | `string` | optional | Action/URL when notification is clicked | + +--- + +## SlackMessageAction + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Action name | +| **type** | `string` | ✅ | | +| **channel** | `string` | ✅ | Slack channel ID or name (#channel) | +| **message** | `string` | ✅ | Message text with optional markdown | +| **mentions** | `string[]` | optional | User IDs or @username to mention | +| **threadId** | `string` | optional | Thread ID for replies | + +--- + +## SmsNotificationAction + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Action name | +| **type** | `string` | ✅ | | +| **provider** | `Enum<'twilio' \| 'vonage'>` | ✅ | SMS provider | +| **recipients** | `string[]` | ✅ | List of phone numbers or user field references | +| **message** | `string` | ✅ | SMS message text or template | +| **fromNumber** | `string` | optional | Sender phone number (provider-specific) | + +--- + +## TaskCreationAction + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Action name | +| **type** | `string` | ✅ | | +| **taskObject** | `string` | ✅ | Task object name (e.g., "task", "project_task") | +| **subject** | `string` | ✅ | Task subject/title | +| **description** | `string` | optional | Task description | +| **assignedTo** | `string` | optional | User ID or field reference for assignee | +| **dueDate** | `string` | optional | Due date (ISO string or formula) | +| **priority** | `string` | optional | Task priority | +| **relatedTo** | `string` | optional | Related record ID or field reference | +| **additionalFields** | `Record` | optional | Additional custom fields | + +--- + +## TeamsMessageAction + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Action name | +| **type** | `string` | ✅ | | +| **channel** | `string` | ✅ | Teams channel ID | +| **message** | `string` | ✅ | Message text with optional markdown | +| **mentions** | `string[]` | optional | User IDs to mention | +| **teamId** | `string` | optional | Team ID (if not in default team) | + +--- + +## TimeTrigger + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | optional | Unique identifier | +| **timeLength** | `integer` | ✅ | Duration amount (e.g. 1, 30) | +| **timeUnit** | `Enum<'minutes' \| 'hours' \| 'days'>` | ✅ | Unit of time | +| **offsetDirection** | `Enum<'before' \| 'after'>` | ✅ | Before or After the reference date | +| **offsetFrom** | `Enum<'trigger_date' \| 'date_field'>` | ✅ | Basis for calculation | +| **dateField** | `string` | optional | Date field to calculate from (required if offsetFrom is date_field) | +| **actions** | `object \| object \| object \| object \| object \| object \| object \| object \| object \| object[]` | ✅ | Actions to execute at the scheduled time | + +--- + +## WebhookTriggerAction + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Action name | +| **type** | `string` | ✅ | | +| **url** | `string` | ✅ | Webhook URL to call | +| **method** | `Enum<'POST' \| 'PUT'>` | optional | HTTP method | +| **headers** | `Record` | optional | Custom headers | +| **payload** | `any` | optional | Webhook payload (uses record data if not specified) | +| **retryOnFailure** | `boolean` | optional | Retry if webhook fails | +| **maxRetries** | `number` | optional | Maximum retry attempts | + +--- + +## WorkflowAction + +--- + +## WorkflowRule + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Unique workflow name (lowercase snake_case) | +| **objectName** | `string` | ✅ | Target Object | +| **triggerType** | `Enum<'on_create' \| 'on_update' \| 'on_create_or_update' \| 'on_delete' \| 'schedule'>` | ✅ | When to evaluate | +| **criteria** | `string` | optional | Formula condition. If TRUE, actions execute. | +| **actions** | `object \| object \| object \| object \| object \| object \| object \| object \| object \| object[]` | optional | Immediate actions | +| **timeTriggers** | `object[]` | optional | Scheduled actions relative to trigger or date field | +| **active** | `boolean` | optional | Whether this workflow is active | +| **reevaluateOnChange** | `boolean` | optional | Re-evaluate rule if field updates change the record validity | + +--- + +## WorkflowTriggerType + +### Allowed Values + +* `on_create` +* `on_update` +* `on_create_or_update` +* `on_delete` +* `schedule` + diff --git a/content/docs/references/automation/workflow/CustomScriptAction.mdx b/content/docs/references/automation/workflow/CustomScriptAction.mdx deleted file mode 100644 index ce65c528f..000000000 --- a/content/docs/references/automation/workflow/CustomScriptAction.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: CustomScriptAction -description: CustomScriptAction Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Action name | -| **type** | `string` | ✅ | | -| **language** | `Enum<'javascript' \| 'typescript' \| 'python'>` | optional | Script language | -| **code** | `string` | ✅ | Script code to execute | -| **timeout** | `number` | optional | Execution timeout in milliseconds | -| **context** | `Record` | optional | Additional context variables | diff --git a/content/docs/references/automation/workflow/EmailAlertAction.mdx b/content/docs/references/automation/workflow/EmailAlertAction.mdx deleted file mode 100644 index e23cd03e0..000000000 --- a/content/docs/references/automation/workflow/EmailAlertAction.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: EmailAlertAction -description: EmailAlertAction Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Action name | -| **type** | `string` | ✅ | | -| **template** | `string` | ✅ | Email template ID/DevName | -| **recipients** | `string[]` | ✅ | List of recipient emails or user IDs | diff --git a/content/docs/references/automation/workflow/FieldUpdateAction.mdx b/content/docs/references/automation/workflow/FieldUpdateAction.mdx deleted file mode 100644 index 62298b986..000000000 --- a/content/docs/references/automation/workflow/FieldUpdateAction.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: FieldUpdateAction -description: FieldUpdateAction Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Action name | -| **type** | `string` | ✅ | | -| **field** | `string` | ✅ | Field to update | -| **value** | `any` | optional | Value or Formula to set | diff --git a/content/docs/references/automation/workflow/HttpCallAction.mdx b/content/docs/references/automation/workflow/HttpCallAction.mdx deleted file mode 100644 index e5bc884ef..000000000 --- a/content/docs/references/automation/workflow/HttpCallAction.mdx +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: HttpCallAction -description: HttpCallAction Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Action name | -| **type** | `string` | ✅ | | -| **url** | `string` | ✅ | Target URL | -| **method** | `Enum<'GET' \| 'POST' \| 'PUT' \| 'PATCH' \| 'DELETE'>` | ✅ | HTTP method | -| **headers** | `Record` | optional | Request headers | -| **body** | `any` | optional | Request body (object/string) | -| **authentication** | `object` | optional | Authentication configuration | -| **timeout** | `number` | optional | Request timeout in milliseconds | diff --git a/content/docs/references/automation/workflow/PushNotificationAction.mdx b/content/docs/references/automation/workflow/PushNotificationAction.mdx deleted file mode 100644 index 77add310e..000000000 --- a/content/docs/references/automation/workflow/PushNotificationAction.mdx +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: PushNotificationAction -description: PushNotificationAction Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Action name | -| **type** | `string` | ✅ | | -| **title** | `string` | ✅ | Notification title | -| **body** | `string` | ✅ | Notification body text | -| **recipients** | `string[]` | ✅ | User IDs or device tokens | -| **data** | `Record` | optional | Additional data payload | -| **badge** | `number` | optional | Badge count (iOS) | -| **sound** | `string` | optional | Notification sound | -| **clickAction** | `string` | optional | Action/URL when notification is clicked | diff --git a/content/docs/references/automation/workflow/SlackMessageAction.mdx b/content/docs/references/automation/workflow/SlackMessageAction.mdx deleted file mode 100644 index 5e634be8a..000000000 --- a/content/docs/references/automation/workflow/SlackMessageAction.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: SlackMessageAction -description: SlackMessageAction Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Action name | -| **type** | `string` | ✅ | | -| **channel** | `string` | ✅ | Slack channel ID or name (#channel) | -| **message** | `string` | ✅ | Message text with optional markdown | -| **mentions** | `string[]` | optional | User IDs or @username to mention | -| **threadId** | `string` | optional | Thread ID for replies | diff --git a/content/docs/references/automation/workflow/SmsNotificationAction.mdx b/content/docs/references/automation/workflow/SmsNotificationAction.mdx deleted file mode 100644 index 9025b4e4a..000000000 --- a/content/docs/references/automation/workflow/SmsNotificationAction.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: SmsNotificationAction -description: SmsNotificationAction Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Action name | -| **type** | `string` | ✅ | | -| **provider** | `Enum<'twilio' \| 'vonage'>` | ✅ | SMS provider | -| **recipients** | `string[]` | ✅ | List of phone numbers or user field references | -| **message** | `string` | ✅ | SMS message text or template | -| **fromNumber** | `string` | optional | Sender phone number (provider-specific) | diff --git a/content/docs/references/automation/workflow/TaskCreationAction.mdx b/content/docs/references/automation/workflow/TaskCreationAction.mdx deleted file mode 100644 index 7b55f6a17..000000000 --- a/content/docs/references/automation/workflow/TaskCreationAction.mdx +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: TaskCreationAction -description: TaskCreationAction Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Action name | -| **type** | `string` | ✅ | | -| **taskObject** | `string` | ✅ | Task object name (e.g., "task", "project_task") | -| **subject** | `string` | ✅ | Task subject/title | -| **description** | `string` | optional | Task description | -| **assignedTo** | `string` | optional | User ID or field reference for assignee | -| **dueDate** | `string` | optional | Due date (ISO string or formula) | -| **priority** | `string` | optional | Task priority | -| **relatedTo** | `string` | optional | Related record ID or field reference | -| **additionalFields** | `Record` | optional | Additional custom fields | diff --git a/content/docs/references/automation/workflow/TeamsMessageAction.mdx b/content/docs/references/automation/workflow/TeamsMessageAction.mdx deleted file mode 100644 index 71804dbf5..000000000 --- a/content/docs/references/automation/workflow/TeamsMessageAction.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: TeamsMessageAction -description: TeamsMessageAction Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Action name | -| **type** | `string` | ✅ | | -| **channel** | `string` | ✅ | Teams channel ID | -| **message** | `string` | ✅ | Message text with optional markdown | -| **mentions** | `string[]` | optional | User IDs to mention | -| **teamId** | `string` | optional | Team ID (if not in default team) | diff --git a/content/docs/references/automation/workflow/TimeTrigger.mdx b/content/docs/references/automation/workflow/TimeTrigger.mdx deleted file mode 100644 index c7f4677aa..000000000 --- a/content/docs/references/automation/workflow/TimeTrigger.mdx +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: TimeTrigger -description: TimeTrigger Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | optional | Unique identifier | -| **timeLength** | `integer` | ✅ | Duration amount (e.g. 1, 30) | -| **timeUnit** | `Enum<'minutes' \| 'hours' \| 'days'>` | ✅ | Unit of time | -| **offsetDirection** | `Enum<'before' \| 'after'>` | ✅ | Before or After the reference date | -| **offsetFrom** | `Enum<'trigger_date' \| 'date_field'>` | ✅ | Basis for calculation | -| **dateField** | `string` | optional | Date field to calculate from (required if offsetFrom is date_field) | -| **actions** | `object \| object \| object \| object \| object \| object \| object \| object \| object \| object[]` | ✅ | Actions to execute at the scheduled time | diff --git a/content/docs/references/automation/workflow/WebhookTriggerAction.mdx b/content/docs/references/automation/workflow/WebhookTriggerAction.mdx deleted file mode 100644 index 207882a30..000000000 --- a/content/docs/references/automation/workflow/WebhookTriggerAction.mdx +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: WebhookTriggerAction -description: WebhookTriggerAction Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Action name | -| **type** | `string` | ✅ | | -| **url** | `string` | ✅ | Webhook URL to call | -| **method** | `Enum<'POST' \| 'PUT'>` | optional | HTTP method | -| **headers** | `Record` | optional | Custom headers | -| **payload** | `any` | optional | Webhook payload (uses record data if not specified) | -| **retryOnFailure** | `boolean` | optional | Retry if webhook fails | -| **maxRetries** | `number` | optional | Maximum retry attempts | diff --git a/content/docs/references/automation/workflow/WorkflowAction.mdx b/content/docs/references/automation/workflow/WorkflowAction.mdx deleted file mode 100644 index 9d45b696a..000000000 --- a/content/docs/references/automation/workflow/WorkflowAction.mdx +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: WorkflowAction -description: WorkflowAction Schema Reference ---- - diff --git a/content/docs/references/automation/workflow/WorkflowRule.mdx b/content/docs/references/automation/workflow/WorkflowRule.mdx deleted file mode 100644 index 88bfca56f..000000000 --- a/content/docs/references/automation/workflow/WorkflowRule.mdx +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: WorkflowRule -description: WorkflowRule Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Unique workflow name (lowercase snake_case) | -| **objectName** | `string` | ✅ | Target Object | -| **triggerType** | `Enum<'on_create' \| 'on_update' \| 'on_create_or_update' \| 'on_delete' \| 'schedule'>` | ✅ | When to evaluate | -| **criteria** | `string` | optional | Formula condition. If TRUE, actions execute. | -| **actions** | `object \| object \| object \| object \| object \| object \| object \| object \| object \| object[]` | optional | Immediate actions | -| **timeTriggers** | `object[]` | optional | Scheduled actions relative to trigger or date field | -| **active** | `boolean` | optional | Whether this workflow is active | -| **reevaluateOnChange** | `boolean` | optional | Re-evaluate rule if field updates change the record validity | diff --git a/content/docs/references/automation/workflow/WorkflowTriggerType.mdx b/content/docs/references/automation/workflow/WorkflowTriggerType.mdx deleted file mode 100644 index 6c5f6564c..000000000 --- a/content/docs/references/automation/workflow/WorkflowTriggerType.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: WorkflowTriggerType -description: WorkflowTriggerType Schema Reference ---- - -## Allowed Values - -* `on_create` -* `on_update` -* `on_create_or_update` -* `on_delete` -* `schedule` \ No newline at end of file diff --git a/content/docs/references/automation/workflow/meta.json b/content/docs/references/automation/workflow/meta.json deleted file mode 100644 index 01a9343dd..000000000 --- a/content/docs/references/automation/workflow/meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "title": "Workflow" -} \ No newline at end of file diff --git a/content/docs/references/data/dataset.mdx b/content/docs/references/data/dataset.mdx new file mode 100644 index 000000000..0cf6ae1da --- /dev/null +++ b/content/docs/references/data/dataset.mdx @@ -0,0 +1,47 @@ +--- +title: Dataset +description: Dataset protocol schemas +--- + +# Dataset + + +**Source:** `packages/spec/src/data/dataset.zod.ts` + + +## TypeScript Usage + +```typescript +import { DatasetSchema, DatasetModeSchema } from '@objectstack/spec/data'; +import type { Dataset, DatasetMode } from '@objectstack/spec/data'; + +// Validate data +const result = DatasetSchema.parse(data); +``` + +--- + +## Dataset + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **object** | `string` | ✅ | Target Object Name | +| **externalId** | `string` | optional | Field match for uniqueness check | +| **mode** | `Enum<'insert' \| 'update' \| 'upsert' \| 'replace' \| 'ignore'>` | optional | Conflict resolution strategy | +| **env** | `Enum<'prod' \| 'dev' \| 'test'>[]` | optional | Applicable environments | +| **records** | `Record[]` | ✅ | Data records | + +--- + +## DatasetMode + +### Allowed Values + +* `insert` +* `update` +* `upsert` +* `replace` +* `ignore` + diff --git a/content/docs/references/data/dataset/Dataset.mdx b/content/docs/references/data/dataset/Dataset.mdx deleted file mode 100644 index 7e003d6e9..000000000 --- a/content/docs/references/data/dataset/Dataset.mdx +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: Dataset -description: Dataset Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **object** | `string` | ✅ | Target Object Name | -| **externalId** | `string` | optional | Field match for uniqueness check | -| **mode** | `Enum<'insert' \| 'update' \| 'upsert' \| 'replace' \| 'ignore'>` | optional | Conflict resolution strategy | -| **env** | `Enum<'prod' \| 'dev' \| 'test'>[]` | optional | Applicable environments | -| **records** | `Record[]` | ✅ | Data records | diff --git a/content/docs/references/data/dataset/DatasetMode.mdx b/content/docs/references/data/dataset/DatasetMode.mdx deleted file mode 100644 index 4366a09d9..000000000 --- a/content/docs/references/data/dataset/DatasetMode.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: DatasetMode -description: DatasetMode Schema Reference ---- - -## Allowed Values - -* `insert` -* `update` -* `upsert` -* `replace` -* `ignore` \ No newline at end of file diff --git a/content/docs/references/data/dataset/meta.json b/content/docs/references/data/dataset/meta.json deleted file mode 100644 index 6e8313b0f..000000000 --- a/content/docs/references/data/dataset/meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "title": "Dataset" -} \ No newline at end of file diff --git a/content/docs/references/data/field/Field.mdx b/content/docs/references/data/field.mdx similarity index 54% rename from content/docs/references/data/field/Field.mdx rename to content/docs/references/data/field.mdx index 8f9b05947..1a9c5ae5c 100644 --- a/content/docs/references/data/field/Field.mdx +++ b/content/docs/references/data/field.mdx @@ -1,9 +1,68 @@ --- title: Field -description: Field Schema Reference +description: Field protocol schemas --- -## Properties +# Field + + +**Source:** `packages/spec/src/data/field.zod.ts` + + +## TypeScript Usage + +```typescript +import { AddressSchema, CurrencyConfigSchema, CurrencyValueSchema, FieldSchema, FieldTypeSchema, LocationCoordinatesSchema, SelectOptionSchema, VectorConfigSchema } from '@objectstack/spec/data'; +import type { Address, CurrencyConfig, CurrencyValue, Field, FieldType, LocationCoordinates, SelectOption, VectorConfig } from '@objectstack/spec/data'; + +// Validate data +const result = AddressSchema.parse(data); +``` + +--- + +## Address + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **street** | `string` | optional | Street address | +| **city** | `string` | optional | City name | +| **state** | `string` | optional | State/Province | +| **postalCode** | `string` | optional | Postal/ZIP code | +| **country** | `string` | optional | Country name or code | +| **countryCode** | `string` | optional | ISO country code (e.g., US, GB) | +| **formatted** | `string` | optional | Formatted address string | + +--- + +## CurrencyConfig + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **precision** | `integer` | optional | Decimal precision (default: 2) | +| **currencyMode** | `Enum<'dynamic' \| 'fixed'>` | optional | Currency mode: dynamic (user selectable) or fixed (single currency) | +| **defaultCurrency** | `string` | optional | Default or fixed currency code (ISO 4217, e.g., USD, CNY, EUR) | + +--- + +## CurrencyValue + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **value** | `number` | ✅ | Monetary amount | +| **currency** | `string` | ✅ | Currency code (ISO 4217) | + +--- + +## Field + +### Properties | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | @@ -56,3 +115,95 @@ description: Field Schema Reference | **encryption** | `boolean` | optional | Encrypt at rest | | **index** | `boolean` | optional | Create standard database index | | **externalId** | `boolean` | optional | Is external ID for upsert operations | + +--- + +## FieldType + +### Allowed Values + +* `text` +* `textarea` +* `email` +* `url` +* `phone` +* `password` +* `markdown` +* `html` +* `richtext` +* `number` +* `currency` +* `percent` +* `date` +* `datetime` +* `time` +* `boolean` +* `toggle` +* `select` +* `multiselect` +* `radio` +* `checkboxes` +* `lookup` +* `master_detail` +* `tree` +* `image` +* `file` +* `avatar` +* `video` +* `audio` +* `formula` +* `summary` +* `autonumber` +* `location` +* `address` +* `code` +* `json` +* `color` +* `rating` +* `slider` +* `signature` +* `qrcode` +* `progress` +* `tags` +* `vector` + +--- + +## LocationCoordinates + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **latitude** | `number` | ✅ | Latitude coordinate | +| **longitude** | `number` | ✅ | Longitude coordinate | +| **altitude** | `number` | optional | Altitude in meters | +| **accuracy** | `number` | optional | Accuracy in meters | + +--- + +## SelectOption + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **label** | `string` | ✅ | Display label (human-readable, any case allowed) | +| **value** | `string` | ✅ | Stored value (lowercase machine identifier) | +| **color** | `string` | optional | Color code for badges/charts | +| **default** | `boolean` | optional | Is default option | + +--- + +## VectorConfig + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **dimensions** | `integer` | ✅ | Vector dimensionality (e.g., 1536 for OpenAI embeddings) | +| **distanceMetric** | `Enum<'cosine' \| 'euclidean' \| 'dotProduct' \| 'manhattan'>` | optional | Distance/similarity metric for vector search | +| **normalized** | `boolean` | optional | Whether vectors are normalized (unit length) | +| **indexed** | `boolean` | optional | Whether to create a vector index for fast similarity search | +| **indexType** | `Enum<'hnsw' \| 'ivfflat' \| 'flat'>` | optional | Vector index algorithm (HNSW for high accuracy, IVFFlat for large datasets) | + diff --git a/content/docs/references/data/field/Address.mdx b/content/docs/references/data/field/Address.mdx deleted file mode 100644 index 1889b8213..000000000 --- a/content/docs/references/data/field/Address.mdx +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: Address -description: Address Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **street** | `string` | optional | Street address | -| **city** | `string` | optional | City name | -| **state** | `string` | optional | State/Province | -| **postalCode** | `string` | optional | Postal/ZIP code | -| **country** | `string` | optional | Country name or code | -| **countryCode** | `string` | optional | ISO country code (e.g., US, GB) | -| **formatted** | `string` | optional | Formatted address string | diff --git a/content/docs/references/data/field/CurrencyConfig.mdx b/content/docs/references/data/field/CurrencyConfig.mdx deleted file mode 100644 index 3bf14db03..000000000 --- a/content/docs/references/data/field/CurrencyConfig.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: CurrencyConfig -description: CurrencyConfig Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **precision** | `integer` | optional | Decimal precision (default: 2) | -| **currencyMode** | `Enum<'dynamic' \| 'fixed'>` | optional | Currency mode: dynamic (user selectable) or fixed (single currency) | -| **defaultCurrency** | `string` | optional | Default or fixed currency code (ISO 4217, e.g., USD, CNY, EUR) | diff --git a/content/docs/references/data/field/CurrencyValue.mdx b/content/docs/references/data/field/CurrencyValue.mdx deleted file mode 100644 index cb7ecbc0e..000000000 --- a/content/docs/references/data/field/CurrencyValue.mdx +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: CurrencyValue -description: CurrencyValue Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **value** | `number` | ✅ | Monetary amount | -| **currency** | `string` | ✅ | Currency code (ISO 4217) | diff --git a/content/docs/references/data/field/FieldType.mdx b/content/docs/references/data/field/FieldType.mdx deleted file mode 100644 index 7aa8b5c80..000000000 --- a/content/docs/references/data/field/FieldType.mdx +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: FieldType -description: FieldType Schema Reference ---- - -## Allowed Values - -* `text` -* `textarea` -* `email` -* `url` -* `phone` -* `password` -* `markdown` -* `html` -* `richtext` -* `number` -* `currency` -* `percent` -* `date` -* `datetime` -* `time` -* `boolean` -* `toggle` -* `select` -* `multiselect` -* `radio` -* `checkboxes` -* `lookup` -* `master_detail` -* `tree` -* `image` -* `file` -* `avatar` -* `video` -* `audio` -* `formula` -* `summary` -* `autonumber` -* `location` -* `address` -* `code` -* `json` -* `color` -* `rating` -* `slider` -* `signature` -* `qrcode` -* `progress` -* `tags` -* `vector` \ No newline at end of file diff --git a/content/docs/references/data/field/LocationCoordinates.mdx b/content/docs/references/data/field/LocationCoordinates.mdx deleted file mode 100644 index d450f72c7..000000000 --- a/content/docs/references/data/field/LocationCoordinates.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: LocationCoordinates -description: LocationCoordinates Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **latitude** | `number` | ✅ | Latitude coordinate | -| **longitude** | `number` | ✅ | Longitude coordinate | -| **altitude** | `number` | optional | Altitude in meters | -| **accuracy** | `number` | optional | Accuracy in meters | diff --git a/content/docs/references/data/field/SelectOption.mdx b/content/docs/references/data/field/SelectOption.mdx deleted file mode 100644 index 095d71ac1..000000000 --- a/content/docs/references/data/field/SelectOption.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: SelectOption -description: SelectOption Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **label** | `string` | ✅ | Display label (human-readable, any case allowed) | -| **value** | `string` | ✅ | Stored value (lowercase machine identifier) | -| **color** | `string` | optional | Color code for badges/charts | -| **default** | `boolean` | optional | Is default option | diff --git a/content/docs/references/data/field/VectorConfig.mdx b/content/docs/references/data/field/VectorConfig.mdx deleted file mode 100644 index 2a2bb5739..000000000 --- a/content/docs/references/data/field/VectorConfig.mdx +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: VectorConfig -description: VectorConfig Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **dimensions** | `integer` | ✅ | Vector dimensionality (e.g., 1536 for OpenAI embeddings) | -| **distanceMetric** | `Enum<'cosine' \| 'euclidean' \| 'dotProduct' \| 'manhattan'>` | optional | Distance/similarity metric for vector search | -| **normalized** | `boolean` | optional | Whether vectors are normalized (unit length) | -| **indexed** | `boolean` | optional | Whether to create a vector index for fast similarity search | -| **indexType** | `Enum<'hnsw' \| 'ivfflat' \| 'flat'>` | optional | Vector index algorithm (HNSW for high accuracy, IVFFlat for large datasets) | diff --git a/content/docs/references/data/field/meta.json b/content/docs/references/data/field/meta.json deleted file mode 100644 index 6731230fb..000000000 --- a/content/docs/references/data/field/meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "title": "Field" -} \ No newline at end of file diff --git a/content/docs/references/data/filter.mdx b/content/docs/references/data/filter.mdx new file mode 100644 index 000000000..3a8afbc3c --- /dev/null +++ b/content/docs/references/data/filter.mdx @@ -0,0 +1,148 @@ +--- +title: Filter +description: Filter protocol schemas +--- + +# Filter + + +**Source:** `packages/spec/src/data/filter.zod.ts` + + +## TypeScript Usage + +```typescript +import { ComparisonOperatorSchema, EqualityOperatorSchema, FieldOperatorsSchema, FieldReferenceSchema, FilterConditionSchema, NormalizedFilterSchema, QueryFilterSchema, RangeOperatorSchema, SetOperatorSchema, SpecialOperatorSchema, StringOperatorSchema } from '@objectstack/spec/data'; +import type { ComparisonOperator, EqualityOperator, FieldOperators, FieldReference, FilterCondition, NormalizedFilter, QueryFilter, RangeOperator, SetOperator, SpecialOperator, StringOperator } from '@objectstack/spec/data'; + +// Validate data +const result = ComparisonOperatorSchema.parse(data); +``` + +--- + +## ComparisonOperator + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **$gt** | `number \| string \| object` | optional | | +| **$gte** | `number \| string \| object` | optional | | +| **$lt** | `number \| string \| object` | optional | | +| **$lte** | `number \| string \| object` | optional | | + +--- + +## EqualityOperator + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **$eq** | `any` | optional | | +| **$ne** | `any` | optional | | + +--- + +## FieldOperators + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **$eq** | `any` | optional | | +| **$ne** | `any` | optional | | +| **$gt** | `number \| string \| object` | optional | | +| **$gte** | `number \| string \| object` | optional | | +| **$lt** | `number \| string \| object` | optional | | +| **$lte** | `number \| string \| object` | optional | | +| **$in** | `any[]` | optional | | +| **$nin** | `any[]` | optional | | +| **$between** | `any[]` | optional | | +| **$contains** | `string` | optional | | +| **$startsWith** | `string` | optional | | +| **$endsWith** | `string` | optional | | +| **$null** | `boolean` | optional | | +| **$exist** | `boolean` | optional | | + +--- + +## FieldReference + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **$field** | `string` | ✅ | Field Reference/Column Name | + +--- + +## FilterCondition + +--- + +## NormalizedFilter + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **$and** | `Record \| any[]` | optional | | +| **$or** | `Record \| any[]` | optional | | +| **$not** | `Record \| any` | optional | | + +--- + +## QueryFilter + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **where** | `any` | optional | | + +--- + +## RangeOperator + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **$between** | `any[]` | optional | | + +--- + +## SetOperator + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **$in** | `any[]` | optional | | +| **$nin** | `any[]` | optional | | + +--- + +## SpecialOperator + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **$null** | `boolean` | optional | | +| **$exist** | `boolean` | optional | | + +--- + +## StringOperator + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **$contains** | `string` | optional | | +| **$startsWith** | `string` | optional | | +| **$endsWith** | `string` | optional | | + diff --git a/content/docs/references/data/filter/ComparisonOperator.mdx b/content/docs/references/data/filter/ComparisonOperator.mdx deleted file mode 100644 index 03e44b00a..000000000 --- a/content/docs/references/data/filter/ComparisonOperator.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: ComparisonOperator -description: ComparisonOperator Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **$gt** | `number \| string \| object` | optional | | -| **$gte** | `number \| string \| object` | optional | | -| **$lt** | `number \| string \| object` | optional | | -| **$lte** | `number \| string \| object` | optional | | diff --git a/content/docs/references/data/filter/EqualityOperator.mdx b/content/docs/references/data/filter/EqualityOperator.mdx deleted file mode 100644 index b7c3a4064..000000000 --- a/content/docs/references/data/filter/EqualityOperator.mdx +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: EqualityOperator -description: EqualityOperator Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **$eq** | `any` | optional | | -| **$ne** | `any` | optional | | diff --git a/content/docs/references/data/filter/FieldOperators.mdx b/content/docs/references/data/filter/FieldOperators.mdx deleted file mode 100644 index 27d4ff041..000000000 --- a/content/docs/references/data/filter/FieldOperators.mdx +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: FieldOperators -description: FieldOperators Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **$eq** | `any` | optional | | -| **$ne** | `any` | optional | | -| **$gt** | `number \| string \| object` | optional | | -| **$gte** | `number \| string \| object` | optional | | -| **$lt** | `number \| string \| object` | optional | | -| **$lte** | `number \| string \| object` | optional | | -| **$in** | `any[]` | optional | | -| **$nin** | `any[]` | optional | | -| **$between** | `any[]` | optional | | -| **$contains** | `string` | optional | | -| **$startsWith** | `string` | optional | | -| **$endsWith** | `string` | optional | | -| **$null** | `boolean` | optional | | -| **$exist** | `boolean` | optional | | diff --git a/content/docs/references/data/filter/FieldReference.mdx b/content/docs/references/data/filter/FieldReference.mdx deleted file mode 100644 index 585ba206b..000000000 --- a/content/docs/references/data/filter/FieldReference.mdx +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: FieldReference -description: FieldReference Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **$field** | `string` | ✅ | Field Reference/Column Name | diff --git a/content/docs/references/data/filter/FilterCondition.mdx b/content/docs/references/data/filter/FilterCondition.mdx deleted file mode 100644 index 622d19051..000000000 --- a/content/docs/references/data/filter/FilterCondition.mdx +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: FilterCondition -description: FilterCondition Schema Reference ---- - diff --git a/content/docs/references/data/filter/NormalizedFilter.mdx b/content/docs/references/data/filter/NormalizedFilter.mdx deleted file mode 100644 index babf352d3..000000000 --- a/content/docs/references/data/filter/NormalizedFilter.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: NormalizedFilter -description: NormalizedFilter Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **$and** | `Record \| any[]` | optional | | -| **$or** | `Record \| any[]` | optional | | -| **$not** | `Record \| any` | optional | | diff --git a/content/docs/references/data/filter/QueryFilter.mdx b/content/docs/references/data/filter/QueryFilter.mdx deleted file mode 100644 index ca1b37363..000000000 --- a/content/docs/references/data/filter/QueryFilter.mdx +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: QueryFilter -description: QueryFilter Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **where** | `any` | optional | | diff --git a/content/docs/references/data/filter/RangeOperator.mdx b/content/docs/references/data/filter/RangeOperator.mdx deleted file mode 100644 index 618f6c323..000000000 --- a/content/docs/references/data/filter/RangeOperator.mdx +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: RangeOperator -description: RangeOperator Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **$between** | `any[]` | optional | | diff --git a/content/docs/references/data/filter/SetOperator.mdx b/content/docs/references/data/filter/SetOperator.mdx deleted file mode 100644 index c3b5290c7..000000000 --- a/content/docs/references/data/filter/SetOperator.mdx +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: SetOperator -description: SetOperator Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **$in** | `any[]` | optional | | -| **$nin** | `any[]` | optional | | diff --git a/content/docs/references/data/filter/SpecialOperator.mdx b/content/docs/references/data/filter/SpecialOperator.mdx deleted file mode 100644 index 65aa64c98..000000000 --- a/content/docs/references/data/filter/SpecialOperator.mdx +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: SpecialOperator -description: SpecialOperator Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **$null** | `boolean` | optional | | -| **$exist** | `boolean` | optional | | diff --git a/content/docs/references/data/filter/StringOperator.mdx b/content/docs/references/data/filter/StringOperator.mdx deleted file mode 100644 index a2b0b6f94..000000000 --- a/content/docs/references/data/filter/StringOperator.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: StringOperator -description: StringOperator Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **$contains** | `string` | optional | | -| **$startsWith** | `string` | optional | | -| **$endsWith** | `string` | optional | | diff --git a/content/docs/references/data/filter/meta.json b/content/docs/references/data/filter/meta.json deleted file mode 100644 index 88580d7e4..000000000 --- a/content/docs/references/data/filter/meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "title": "Filter" -} \ No newline at end of file diff --git a/content/docs/references/data/hook.mdx b/content/docs/references/data/hook.mdx new file mode 100644 index 000000000..3a4e856a9 --- /dev/null +++ b/content/docs/references/data/hook.mdx @@ -0,0 +1,81 @@ +--- +title: Hook +description: Hook protocol schemas +--- + +# Hook + + +**Source:** `packages/spec/src/data/hook.zod.ts` + + +## TypeScript Usage + +```typescript +import { HookSchema, HookContextSchema, HookEventSchema } from '@objectstack/spec/data'; +import type { Hook, HookContext, HookEvent } from '@objectstack/spec/data'; + +// Validate data +const result = HookSchema.parse(data); +``` + +--- + +## Hook + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Hook unique name (snake_case) | +| **label** | `string` | optional | Description of what this hook does | +| **object** | `string \| string[]` | ✅ | Target object(s) | +| **events** | `Enum<'beforeFind' \| 'afterFind' \| 'beforeFindOne' \| 'afterFindOne' \| 'beforeCount' \| 'afterCount' \| 'beforeAggregate' \| 'afterAggregate' \| 'beforeInsert' \| 'afterInsert' \| 'beforeUpdate' \| 'afterUpdate' \| 'beforeDelete' \| 'afterDelete' \| 'beforeUpdateMany' \| 'afterUpdateMany' \| 'beforeDeleteMany' \| 'afterDeleteMany'>[]` | ✅ | Lifecycle events | +| **handler** | `string \| any` | optional | Function handler name or direct function | +| **priority** | `number` | optional | Execution priority | +| **async** | `boolean` | optional | Run specifically as fire-and-forget | +| **onError** | `Enum<'abort' \| 'log'>` | optional | Error handling strategy | + +--- + +## HookContext + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | optional | Unique execution ID for tracing | +| **object** | `string` | ✅ | | +| **event** | `Enum<'beforeFind' \| 'afterFind' \| 'beforeFindOne' \| 'afterFindOne' \| 'beforeCount' \| 'afterCount' \| 'beforeAggregate' \| 'afterAggregate' \| 'beforeInsert' \| 'afterInsert' \| 'beforeUpdate' \| 'afterUpdate' \| 'beforeDelete' \| 'afterDelete' \| 'beforeUpdateMany' \| 'afterUpdateMany' \| 'beforeDeleteMany' \| 'afterDeleteMany'>` | ✅ | | +| **input** | `Record` | ✅ | Mutable input parameters | +| **result** | `any` | optional | Operation result (After hooks only) | +| **previous** | `Record` | optional | Record state before operation | +| **session** | `object` | optional | Current session context | +| **transaction** | `any` | optional | Database transaction handle | +| **ql** | `any` | optional | ObjectQL Engine Reference | + +--- + +## HookEvent + +### Allowed Values + +* `beforeFind` +* `afterFind` +* `beforeFindOne` +* `afterFindOne` +* `beforeCount` +* `afterCount` +* `beforeAggregate` +* `afterAggregate` +* `beforeInsert` +* `afterInsert` +* `beforeUpdate` +* `afterUpdate` +* `beforeDelete` +* `afterDelete` +* `beforeUpdateMany` +* `afterUpdateMany` +* `beforeDeleteMany` +* `afterDeleteMany` + diff --git a/content/docs/references/data/hook/Hook.mdx b/content/docs/references/data/hook/Hook.mdx deleted file mode 100644 index 11e76ccdd..000000000 --- a/content/docs/references/data/hook/Hook.mdx +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: Hook -description: Hook Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Hook unique name (snake_case) | -| **label** | `string` | optional | Description of what this hook does | -| **object** | `string \| string[]` | ✅ | Target object(s) | -| **events** | `Enum<'beforeFind' \| 'afterFind' \| 'beforeFindOne' \| 'afterFindOne' \| 'beforeCount' \| 'afterCount' \| 'beforeAggregate' \| 'afterAggregate' \| 'beforeInsert' \| 'afterInsert' \| 'beforeUpdate' \| 'afterUpdate' \| 'beforeDelete' \| 'afterDelete' \| 'beforeUpdateMany' \| 'afterUpdateMany' \| 'beforeDeleteMany' \| 'afterDeleteMany'>[]` | ✅ | Lifecycle events | -| **handler** | `string \| any` | optional | Function handler name or direct function | -| **priority** | `number` | optional | Execution priority | -| **async** | `boolean` | optional | Run specifically as fire-and-forget | -| **onError** | `Enum<'abort' \| 'log'>` | optional | Error handling strategy | diff --git a/content/docs/references/data/hook/HookContext.mdx b/content/docs/references/data/hook/HookContext.mdx deleted file mode 100644 index a01727c76..000000000 --- a/content/docs/references/data/hook/HookContext.mdx +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: HookContext -description: HookContext Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | optional | Unique execution ID for tracing | -| **object** | `string` | ✅ | | -| **event** | `Enum<'beforeFind' \| 'afterFind' \| 'beforeFindOne' \| 'afterFindOne' \| 'beforeCount' \| 'afterCount' \| 'beforeAggregate' \| 'afterAggregate' \| 'beforeInsert' \| 'afterInsert' \| 'beforeUpdate' \| 'afterUpdate' \| 'beforeDelete' \| 'afterDelete' \| 'beforeUpdateMany' \| 'afterUpdateMany' \| 'beforeDeleteMany' \| 'afterDeleteMany'>` | ✅ | | -| **input** | `Record` | ✅ | Mutable input parameters | -| **result** | `any` | optional | Operation result (After hooks only) | -| **previous** | `Record` | optional | Record state before operation | -| **session** | `object` | optional | Current session context | -| **transaction** | `any` | optional | Database transaction handle | -| **ql** | `any` | optional | ObjectQL Engine Reference | diff --git a/content/docs/references/data/hook/HookEvent.mdx b/content/docs/references/data/hook/HookEvent.mdx deleted file mode 100644 index 3b25c657e..000000000 --- a/content/docs/references/data/hook/HookEvent.mdx +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: HookEvent -description: HookEvent Schema Reference ---- - -## Allowed Values - -* `beforeFind` -* `afterFind` -* `beforeFindOne` -* `afterFindOne` -* `beforeCount` -* `afterCount` -* `beforeAggregate` -* `afterAggregate` -* `beforeInsert` -* `afterInsert` -* `beforeUpdate` -* `afterUpdate` -* `beforeDelete` -* `afterDelete` -* `beforeUpdateMany` -* `afterUpdateMany` -* `beforeDeleteMany` -* `afterDeleteMany` \ No newline at end of file diff --git a/content/docs/references/data/hook/meta.json b/content/docs/references/data/hook/meta.json deleted file mode 100644 index f34deeaf7..000000000 --- a/content/docs/references/data/hook/meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "title": "Hook" -} \ No newline at end of file diff --git a/content/docs/references/data/index.mdx b/content/docs/references/data/index.mdx new file mode 100644 index 000000000..a91672d32 --- /dev/null +++ b/content/docs/references/data/index.mdx @@ -0,0 +1,20 @@ +--- +title: Data Protocol Overview +description: Complete reference for all data protocol schemas +--- + +# Data Protocol + +This section contains all protocol schemas for the data layer of ObjectStack. + + + + + + + + + + + + diff --git a/content/docs/references/data/mapping/meta.json b/content/docs/references/data/mapping/meta.json deleted file mode 100644 index 868fa1e73..000000000 --- a/content/docs/references/data/mapping/meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "title": "Mapping" -} \ No newline at end of file diff --git a/content/docs/references/data/object.mdx b/content/docs/references/data/object.mdx new file mode 100644 index 000000000..6ed03fba6 --- /dev/null +++ b/content/docs/references/data/object.mdx @@ -0,0 +1,92 @@ +--- +title: Object +description: Object protocol schemas +--- + +# Object + + +**Source:** `packages/spec/src/data/object.zod.ts` + + +## TypeScript Usage + +```typescript +import { IndexSchema, ObjectSchema, ObjectCapabilitiesSchema, SearchConfigSchema } from '@objectstack/spec/data'; +import type { Index, Object, ObjectCapabilities, SearchConfig } from '@objectstack/spec/data'; + +// Validate data +const result = IndexSchema.parse(data); +``` + +--- + +## Index + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | optional | Index name | +| **fields** | `string[]` | ✅ | Fields included in the index | +| **unique** | `boolean` | optional | Whether the index is unique | +| **type** | `Enum<'btree' \| 'hash' \| 'gin' \| 'gist'>` | optional | Index type (default: btree) | + +--- + +## Object + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Machine unique key (snake_case). Immutable. | +| **label** | `string` | optional | Human readable singular label (e.g. "Account") | +| **pluralLabel** | `string` | optional | Human readable plural label (e.g. "Accounts") | +| **description** | `string` | optional | Developer documentation / description | +| **icon** | `string` | optional | Icon name (Lucide/Material) for UI representation | +| **tags** | `string[]` | optional | Categorization tags (e.g. "sales", "system", "reference") | +| **active** | `boolean` | optional | Is the object active and usable | +| **isSystem** | `boolean` | optional | Is system object (protected from deletion) | +| **abstract** | `boolean` | optional | Is abstract base object (cannot be instantiated) | +| **datasource** | `string` | optional | Target Datasource ID. "default" is the primary DB. | +| **tableName** | `string` | optional | Physical table/collection name in the target datasource | +| **fields** | `Record` | ✅ | Field definitions map | +| **indexes** | `object[]` | optional | Database performance indexes | +| **validations** | `object \| object \| object \| object \| object \| object \| object \| object \| object[]` | optional | Object-level validation rules | +| **titleFormat** | `string` | optional | Title expression (e.g. "`{name}` - `{code}`"). Overrides nameField. | +| **compactLayout** | `string[]` | optional | Primary fields for hover/cards/lookups | +| **search** | `object` | optional | Search engine configuration | +| **enable** | `object` | optional | Enabled system features modules | + +--- + +## ObjectCapabilities + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **trackHistory** | `boolean` | optional | Enable field history tracking for audit compliance | +| **searchable** | `boolean` | optional | Index records for global search | +| **apiEnabled** | `boolean` | optional | Expose object via automatic APIs | +| **apiMethods** | `Enum<'get' \| 'list' \| 'create' \| 'update' \| 'delete' \| 'upsert' \| 'bulk' \| 'aggregate' \| 'history' \| 'search' \| 'restore' \| 'purge' \| 'import' \| 'export'>[]` | optional | Whitelist of allowed API operations | +| **files** | `boolean` | optional | Enable file attachments and document management | +| **feeds** | `boolean` | optional | Enable social feed, comments, and mentions (Chatter-like) | +| **activities** | `boolean` | optional | Enable standard tasks and events tracking | +| **trash** | `boolean` | optional | Enable soft-delete with restore capability | +| **mru** | `boolean` | optional | Track Most Recently Used (MRU) list for users | +| **clone** | `boolean` | optional | Allow record deep cloning | + +--- + +## SearchConfig + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **fields** | `string[]` | ✅ | Fields to index for full-text search weighting | +| **displayFields** | `string[]` | optional | Fields to display in search result cards | +| **filters** | `string[]` | optional | Default filters for search results | + diff --git a/content/docs/references/data/object/Index.mdx b/content/docs/references/data/object/Index.mdx deleted file mode 100644 index e8059bb62..000000000 --- a/content/docs/references/data/object/Index.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Index -description: Index Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | optional | Index name | -| **fields** | `string[]` | ✅ | Fields included in the index | -| **unique** | `boolean` | optional | Whether the index is unique | -| **type** | `Enum<'btree' \| 'hash' \| 'gin' \| 'gist'>` | optional | Index type (default: btree) | diff --git a/content/docs/references/data/object/Object.mdx b/content/docs/references/data/object/Object.mdx deleted file mode 100644 index d9aca8c56..000000000 --- a/content/docs/references/data/object/Object.mdx +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: Object -description: Object Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Machine unique key (snake_case). Immutable. | -| **label** | `string` | optional | Human readable singular label (e.g. "Account") | -| **pluralLabel** | `string` | optional | Human readable plural label (e.g. "Accounts") | -| **description** | `string` | optional | Developer documentation / description | -| **icon** | `string` | optional | Icon name (Lucide/Material) for UI representation | -| **tags** | `string[]` | optional | Categorization tags (e.g. "sales", "system", "reference") | -| **active** | `boolean` | optional | Is the object active and usable | -| **isSystem** | `boolean` | optional | Is system object (protected from deletion) | -| **abstract** | `boolean` | optional | Is abstract base object (cannot be instantiated) | -| **datasource** | `string` | optional | Target Datasource ID. "default" is the primary DB. | -| **tableName** | `string` | optional | Physical table/collection name in the target datasource | -| **fields** | `Record` | ✅ | Field definitions map | -| **indexes** | `object[]` | optional | Database performance indexes | -| **validations** | `object \| object \| object \| object \| object \| object \| object \| object \| object[]` | optional | Object-level validation rules | -| **titleFormat** | `string` | optional | Title expression (e.g. "`{name}` - `{code}`"). Overrides nameField. | -| **compactLayout** | `string[]` | optional | Primary fields for hover/cards/lookups | -| **search** | `object` | optional | Search engine configuration | -| **enable** | `object` | optional | Enabled system features modules | diff --git a/content/docs/references/data/object/ObjectCapabilities.mdx b/content/docs/references/data/object/ObjectCapabilities.mdx deleted file mode 100644 index 14d269fdc..000000000 --- a/content/docs/references/data/object/ObjectCapabilities.mdx +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: ObjectCapabilities -description: ObjectCapabilities Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **trackHistory** | `boolean` | optional | Enable field history tracking for audit compliance | -| **searchable** | `boolean` | optional | Index records for global search | -| **apiEnabled** | `boolean` | optional | Expose object via automatic APIs | -| **apiMethods** | `Enum<'get' \| 'list' \| 'create' \| 'update' \| 'delete' \| 'upsert' \| 'bulk' \| 'aggregate' \| 'history' \| 'search' \| 'restore' \| 'purge' \| 'import' \| 'export'>[]` | optional | Whitelist of allowed API operations | -| **files** | `boolean` | optional | Enable file attachments and document management | -| **feeds** | `boolean` | optional | Enable social feed, comments, and mentions (Chatter-like) | -| **activities** | `boolean` | optional | Enable standard tasks and events tracking | -| **trash** | `boolean` | optional | Enable soft-delete with restore capability | -| **mru** | `boolean` | optional | Track Most Recently Used (MRU) list for users | -| **clone** | `boolean` | optional | Allow record deep cloning | diff --git a/content/docs/references/data/object/SearchConfig.mdx b/content/docs/references/data/object/SearchConfig.mdx deleted file mode 100644 index fa44545ea..000000000 --- a/content/docs/references/data/object/SearchConfig.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: SearchConfig -description: SearchConfig Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **fields** | `string[]` | ✅ | Fields to index for full-text search weighting | -| **displayFields** | `string[]` | optional | Fields to display in search result cards | -| **filters** | `string[]` | optional | Default filters for search results | diff --git a/content/docs/references/data/object/meta.json b/content/docs/references/data/object/meta.json deleted file mode 100644 index 60779931f..000000000 --- a/content/docs/references/data/object/meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "title": "Object" -} \ No newline at end of file diff --git a/content/docs/references/data/query.mdx b/content/docs/references/data/query.mdx new file mode 100644 index 000000000..aabc1e68b --- /dev/null +++ b/content/docs/references/data/query.mdx @@ -0,0 +1,169 @@ +--- +title: Query +description: Query protocol schemas +--- + +# Query + + +**Source:** `packages/spec/src/data/query.zod.ts` + + +## TypeScript Usage + +```typescript +import { AggregationFunctionSchema, AggregationNodeSchema, FieldNodeSchema, JoinNodeSchema, JoinStrategySchema, JoinTypeSchema, QuerySchema, SortNodeSchema, WindowFunctionSchema, WindowFunctionNodeSchema, WindowSpecSchema } from '@objectstack/spec/data'; +import type { AggregationFunction, AggregationNode, FieldNode, JoinNode, JoinStrategy, JoinType, Query, SortNode, WindowFunction, WindowFunctionNode, WindowSpec } from '@objectstack/spec/data'; + +// Validate data +const result = AggregationFunctionSchema.parse(data); +``` + +--- + +## AggregationFunction + +### Allowed Values + +* `count` +* `sum` +* `avg` +* `min` +* `max` +* `count_distinct` +* `array_agg` +* `string_agg` + +--- + +## AggregationNode + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **function** | `Enum<'count' \| 'sum' \| 'avg' \| 'min' \| 'max' \| 'count_distinct' \| 'array_agg' \| 'string_agg'>` | ✅ | Aggregation function | +| **field** | `string` | optional | Field to aggregate (optional for COUNT(*)) | +| **alias** | `string` | ✅ | Result column alias | +| **distinct** | `boolean` | optional | Apply DISTINCT before aggregation | +| **filter** | `any` | optional | Filter/Condition to apply to the aggregation (FILTER WHERE clause) | + +--- + +## FieldNode + +--- + +## JoinNode + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **type** | `Enum<'inner' \| 'left' \| 'right' \| 'full'>` | ✅ | Join type | +| **strategy** | `Enum<'auto' \| 'database' \| 'hash' \| 'loop'>` | optional | Execution strategy hint | +| **object** | `string` | ✅ | Object/table to join | +| **alias** | `string` | optional | Table alias | +| **on** | `any` | ✅ | Join condition | +| **subquery** | `object` | optional | Subquery instead of object | + +--- + +## JoinStrategy + +### Allowed Values + +* `auto` +* `database` +* `hash` +* `loop` + +--- + +## JoinType + +### Allowed Values + +* `inner` +* `left` +* `right` +* `full` + +--- + +## Query + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **object** | `string` | ✅ | Object name (e.g. account) | +| **fields** | `string \| object[]` | optional | Fields to retrieve | +| **where** | `any` | optional | Filtering criteria (WHERE) | +| **orderBy** | `object[]` | optional | Sorting instructions (ORDER BY) | +| **limit** | `number` | optional | Max records to return (LIMIT) | +| **offset** | `number` | optional | Records to skip (OFFSET) | +| **cursor** | `Record` | optional | Cursor for keyset pagination | +| **joins** | `object[]` | optional | Explicit Table Joins | +| **aggregations** | `object[]` | optional | Aggregation functions | +| **groupBy** | `string[]` | optional | GROUP BY fields | +| **having** | `any` | optional | HAVING clause for aggregation filtering | +| **windowFunctions** | `object[]` | optional | Window functions with OVER clause | +| **distinct** | `boolean` | optional | SELECT DISTINCT flag | + +--- + +## SortNode + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **field** | `string` | ✅ | | +| **order** | `Enum<'asc' \| 'desc'>` | optional | | + +--- + +## WindowFunction + +### Allowed Values + +* `row_number` +* `rank` +* `dense_rank` +* `percent_rank` +* `lag` +* `lead` +* `first_value` +* `last_value` +* `sum` +* `avg` +* `count` +* `min` +* `max` + +--- + +## WindowFunctionNode + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **function** | `Enum<'row_number' \| 'rank' \| 'dense_rank' \| 'percent_rank' \| 'lag' \| 'lead' \| 'first_value' \| 'last_value' \| 'sum' \| 'avg' \| 'count' \| 'min' \| 'max'>` | ✅ | Window function name | +| **field** | `string` | optional | Field to operate on (for aggregate window functions) | +| **alias** | `string` | ✅ | Result column alias | +| **over** | `object` | ✅ | Window specification (OVER clause) | + +--- + +## WindowSpec + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **partitionBy** | `string[]` | optional | PARTITION BY fields | +| **orderBy** | `object[]` | optional | ORDER BY specification | +| **frame** | `object` | optional | Window frame specification | + diff --git a/content/docs/references/data/query/AggregationFunction.mdx b/content/docs/references/data/query/AggregationFunction.mdx deleted file mode 100644 index 9477b17f8..000000000 --- a/content/docs/references/data/query/AggregationFunction.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: AggregationFunction -description: AggregationFunction Schema Reference ---- - -## Allowed Values - -* `count` -* `sum` -* `avg` -* `min` -* `max` -* `count_distinct` -* `array_agg` -* `string_agg` \ No newline at end of file diff --git a/content/docs/references/data/query/AggregationNode.mdx b/content/docs/references/data/query/AggregationNode.mdx deleted file mode 100644 index aa9a4d7c4..000000000 --- a/content/docs/references/data/query/AggregationNode.mdx +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: AggregationNode -description: AggregationNode Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **function** | `Enum<'count' \| 'sum' \| 'avg' \| 'min' \| 'max' \| 'count_distinct' \| 'array_agg' \| 'string_agg'>` | ✅ | Aggregation function | -| **field** | `string` | optional | Field to aggregate (optional for COUNT(*)) | -| **alias** | `string` | ✅ | Result column alias | -| **distinct** | `boolean` | optional | Apply DISTINCT before aggregation | -| **filter** | `any` | optional | Filter/Condition to apply to the aggregation (FILTER WHERE clause) | diff --git a/content/docs/references/data/query/FieldNode.mdx b/content/docs/references/data/query/FieldNode.mdx deleted file mode 100644 index 7f363499b..000000000 --- a/content/docs/references/data/query/FieldNode.mdx +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: FieldNode -description: FieldNode Schema Reference ---- - diff --git a/content/docs/references/data/query/JoinNode.mdx b/content/docs/references/data/query/JoinNode.mdx deleted file mode 100644 index 120379e0f..000000000 --- a/content/docs/references/data/query/JoinNode.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: JoinNode -description: JoinNode Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `Enum<'inner' \| 'left' \| 'right' \| 'full'>` | ✅ | Join type | -| **strategy** | `Enum<'auto' \| 'database' \| 'hash' \| 'loop'>` | optional | Execution strategy hint | -| **object** | `string` | ✅ | Object/table to join | -| **alias** | `string` | optional | Table alias | -| **on** | `any` | ✅ | Join condition | -| **subquery** | `object` | optional | Subquery instead of object | diff --git a/content/docs/references/data/query/JoinStrategy.mdx b/content/docs/references/data/query/JoinStrategy.mdx deleted file mode 100644 index cab1eaca1..000000000 --- a/content/docs/references/data/query/JoinStrategy.mdx +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: JoinStrategy -description: JoinStrategy Schema Reference ---- - -## Allowed Values - -* `auto` -* `database` -* `hash` -* `loop` \ No newline at end of file diff --git a/content/docs/references/data/query/JoinType.mdx b/content/docs/references/data/query/JoinType.mdx deleted file mode 100644 index b83d28253..000000000 --- a/content/docs/references/data/query/JoinType.mdx +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: JoinType -description: JoinType Schema Reference ---- - -## Allowed Values - -* `inner` -* `left` -* `right` -* `full` \ No newline at end of file diff --git a/content/docs/references/data/query/Query.mdx b/content/docs/references/data/query/Query.mdx deleted file mode 100644 index 1d809d213..000000000 --- a/content/docs/references/data/query/Query.mdx +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: Query -description: Query Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **object** | `string` | ✅ | Object name (e.g. account) | -| **fields** | `string \| object[]` | optional | Fields to retrieve | -| **where** | `any` | optional | Filtering criteria (WHERE) | -| **orderBy** | `object[]` | optional | Sorting instructions (ORDER BY) | -| **limit** | `number` | optional | Max records to return (LIMIT) | -| **offset** | `number` | optional | Records to skip (OFFSET) | -| **cursor** | `Record` | optional | Cursor for keyset pagination | -| **joins** | `object[]` | optional | Explicit Table Joins | -| **aggregations** | `object[]` | optional | Aggregation functions | -| **groupBy** | `string[]` | optional | GROUP BY fields | -| **having** | `any` | optional | HAVING clause for aggregation filtering | -| **windowFunctions** | `object[]` | optional | Window functions with OVER clause | -| **distinct** | `boolean` | optional | SELECT DISTINCT flag | diff --git a/content/docs/references/data/query/SortNode.mdx b/content/docs/references/data/query/SortNode.mdx deleted file mode 100644 index 1574f19bc..000000000 --- a/content/docs/references/data/query/SortNode.mdx +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: SortNode -description: SortNode Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **field** | `string` | ✅ | | -| **order** | `Enum<'asc' \| 'desc'>` | optional | | diff --git a/content/docs/references/data/query/WindowFunction.mdx b/content/docs/references/data/query/WindowFunction.mdx deleted file mode 100644 index 598d21b6b..000000000 --- a/content/docs/references/data/query/WindowFunction.mdx +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: WindowFunction -description: WindowFunction Schema Reference ---- - -## Allowed Values - -* `row_number` -* `rank` -* `dense_rank` -* `percent_rank` -* `lag` -* `lead` -* `first_value` -* `last_value` -* `sum` -* `avg` -* `count` -* `min` -* `max` \ No newline at end of file diff --git a/content/docs/references/data/query/WindowFunctionNode.mdx b/content/docs/references/data/query/WindowFunctionNode.mdx deleted file mode 100644 index c0a9f0e9b..000000000 --- a/content/docs/references/data/query/WindowFunctionNode.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: WindowFunctionNode -description: WindowFunctionNode Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **function** | `Enum<'row_number' \| 'rank' \| 'dense_rank' \| 'percent_rank' \| 'lag' \| 'lead' \| 'first_value' \| 'last_value' \| 'sum' \| 'avg' \| 'count' \| 'min' \| 'max'>` | ✅ | Window function name | -| **field** | `string` | optional | Field to operate on (for aggregate window functions) | -| **alias** | `string` | ✅ | Result column alias | -| **over** | `object` | ✅ | Window specification (OVER clause) | diff --git a/content/docs/references/data/query/WindowSpec.mdx b/content/docs/references/data/query/WindowSpec.mdx deleted file mode 100644 index 0093f8533..000000000 --- a/content/docs/references/data/query/WindowSpec.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: WindowSpec -description: WindowSpec Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **partitionBy** | `string[]` | optional | PARTITION BY fields | -| **orderBy** | `object[]` | optional | ORDER BY specification | -| **frame** | `object` | optional | Window frame specification | diff --git a/content/docs/references/data/query/meta.json b/content/docs/references/data/query/meta.json deleted file mode 100644 index 00be5107e..000000000 --- a/content/docs/references/data/query/meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "title": "Query" -} \ No newline at end of file diff --git a/content/docs/references/data/validation.mdx b/content/docs/references/data/validation.mdx new file mode 100644 index 000000000..ebcf1cdb8 --- /dev/null +++ b/content/docs/references/data/validation.mdx @@ -0,0 +1,213 @@ +--- +title: Validation +description: Validation protocol schemas +--- + +# Validation + + +**Source:** `packages/spec/src/data/validation.zod.ts` + + +## TypeScript Usage + +```typescript +import { AsyncValidationSchema, ConditionalValidationSchema, CrossFieldValidationSchema, CustomValidatorSchema, FormatValidationSchema, JSONValidationSchema, ScriptValidationSchema, StateMachineValidationSchema, UniquenessValidationSchema, ValidationRuleSchema } from '@objectstack/spec/data'; +import type { AsyncValidation, ConditionalValidation, CrossFieldValidation, CustomValidator, FormatValidation, JSONValidation, ScriptValidation, StateMachineValidation, UniquenessValidation, ValidationRule } from '@objectstack/spec/data'; + +// Validate data +const result = AsyncValidationSchema.parse(data); +``` + +--- + +## AsyncValidation + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Unique rule name (snake_case) | +| **label** | `string` | optional | Human-readable label for the rule listing | +| **description** | `string` | optional | Administrative notes explaining the business reason | +| **active** | `boolean` | optional | | +| **events** | `Enum<'insert' \| 'update' \| 'delete'>[]` | optional | Validation contexts | +| **tags** | `string[]` | optional | Categorization tags (e.g., "compliance", "billing") | +| **severity** | `Enum<'error' \| 'warning' \| 'info'>` | optional | | +| **message** | `string` | ✅ | Error message to display to the user | +| **type** | `string` | ✅ | | +| **field** | `string` | ✅ | Field to validate | +| **validatorUrl** | `string` | optional | External API endpoint for validation | +| **method** | `Enum<'GET' \| 'POST'>` | optional | HTTP method for external call | +| **headers** | `Record` | optional | Custom headers for the request | +| **validatorFunction** | `string` | optional | Reference to custom validator function | +| **timeout** | `number` | optional | Timeout in milliseconds | +| **debounce** | `number` | optional | Debounce delay in milliseconds | +| **params** | `Record` | optional | Additional parameters to pass to validator | + +--- + +## ConditionalValidation + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Unique rule name (snake_case) | +| **label** | `string` | optional | Human-readable label for the rule listing | +| **description** | `string` | optional | Administrative notes explaining the business reason | +| **active** | `boolean` | optional | | +| **events** | `Enum<'insert' \| 'update' \| 'delete'>[]` | optional | Validation contexts | +| **tags** | `string[]` | optional | Categorization tags (e.g., "compliance", "billing") | +| **severity** | `Enum<'error' \| 'warning' \| 'info'>` | optional | | +| **message** | `string` | ✅ | Error message to display to the user | +| **type** | `string` | ✅ | | +| **when** | `string` | ✅ | Condition formula (e.g. "type = 'enterprise'") | +| **then** | `object \| object \| object \| object \| object \| object \| object \| object \| any` | ✅ | Validation rule to apply when condition is true | +| **otherwise** | `object \| object \| object \| object \| object \| object \| object \| object \| any` | optional | Validation rule to apply when condition is false | + +--- + +## CrossFieldValidation + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Unique rule name (snake_case) | +| **label** | `string` | optional | Human-readable label for the rule listing | +| **description** | `string` | optional | Administrative notes explaining the business reason | +| **active** | `boolean` | optional | | +| **events** | `Enum<'insert' \| 'update' \| 'delete'>[]` | optional | Validation contexts | +| **tags** | `string[]` | optional | Categorization tags (e.g., "compliance", "billing") | +| **severity** | `Enum<'error' \| 'warning' \| 'info'>` | optional | | +| **message** | `string` | ✅ | Error message to display to the user | +| **type** | `string` | ✅ | | +| **condition** | `string` | ✅ | Formula expression comparing fields (e.g. "end_date > start_date") | +| **fields** | `string[]` | ✅ | Fields involved in the validation | + +--- + +## CustomValidator + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Unique rule name (snake_case) | +| **label** | `string` | optional | Human-readable label for the rule listing | +| **description** | `string` | optional | Administrative notes explaining the business reason | +| **active** | `boolean` | optional | | +| **events** | `Enum<'insert' \| 'update' \| 'delete'>[]` | optional | Validation contexts | +| **tags** | `string[]` | optional | Categorization tags (e.g., "compliance", "billing") | +| **severity** | `Enum<'error' \| 'warning' \| 'info'>` | optional | | +| **message** | `string` | ✅ | Error message to display to the user | +| **type** | `string` | ✅ | | +| **handler** | `string` | ✅ | Name of the custom validation function registered in the system | +| **params** | `Record` | optional | Parameters passed to the custom handler | + +--- + +## FormatValidation + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Unique rule name (snake_case) | +| **label** | `string` | optional | Human-readable label for the rule listing | +| **description** | `string` | optional | Administrative notes explaining the business reason | +| **active** | `boolean` | optional | | +| **events** | `Enum<'insert' \| 'update' \| 'delete'>[]` | optional | Validation contexts | +| **tags** | `string[]` | optional | Categorization tags (e.g., "compliance", "billing") | +| **severity** | `Enum<'error' \| 'warning' \| 'info'>` | optional | | +| **message** | `string` | ✅ | Error message to display to the user | +| **type** | `string` | ✅ | | +| **field** | `string` | ✅ | | +| **regex** | `string` | optional | | +| **format** | `Enum<'email' \| 'url' \| 'phone' \| 'json'>` | optional | | + +--- + +## JSONValidation + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Unique rule name (snake_case) | +| **label** | `string` | optional | Human-readable label for the rule listing | +| **description** | `string` | optional | Administrative notes explaining the business reason | +| **active** | `boolean` | optional | | +| **events** | `Enum<'insert' \| 'update' \| 'delete'>[]` | optional | Validation contexts | +| **tags** | `string[]` | optional | Categorization tags (e.g., "compliance", "billing") | +| **severity** | `Enum<'error' \| 'warning' \| 'info'>` | optional | | +| **message** | `string` | ✅ | Error message to display to the user | +| **type** | `string` | ✅ | | +| **field** | `string` | ✅ | JSON field to validate | +| **schema** | `Record` | ✅ | JSON Schema object definition | + +--- + +## ScriptValidation + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Unique rule name (snake_case) | +| **label** | `string` | optional | Human-readable label for the rule listing | +| **description** | `string` | optional | Administrative notes explaining the business reason | +| **active** | `boolean` | optional | | +| **events** | `Enum<'insert' \| 'update' \| 'delete'>[]` | optional | Validation contexts | +| **tags** | `string[]` | optional | Categorization tags (e.g., "compliance", "billing") | +| **severity** | `Enum<'error' \| 'warning' \| 'info'>` | optional | | +| **message** | `string` | ✅ | Error message to display to the user | +| **type** | `string` | ✅ | | +| **condition** | `string` | ✅ | Formula expression. If TRUE, validation fails. (e.g. amount < 0) | + +--- + +## StateMachineValidation + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Unique rule name (snake_case) | +| **label** | `string` | optional | Human-readable label for the rule listing | +| **description** | `string` | optional | Administrative notes explaining the business reason | +| **active** | `boolean` | optional | | +| **events** | `Enum<'insert' \| 'update' \| 'delete'>[]` | optional | Validation contexts | +| **tags** | `string[]` | optional | Categorization tags (e.g., "compliance", "billing") | +| **severity** | `Enum<'error' \| 'warning' \| 'info'>` | optional | | +| **message** | `string` | ✅ | Error message to display to the user | +| **type** | `string` | ✅ | | +| **field** | `string` | ✅ | State field (e.g. status) | +| **transitions** | `Record` | ✅ | Map of `{ OldState: [AllowedNewStates] }` | + +--- + +## UniquenessValidation + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Unique rule name (snake_case) | +| **label** | `string` | optional | Human-readable label for the rule listing | +| **description** | `string` | optional | Administrative notes explaining the business reason | +| **active** | `boolean` | optional | | +| **events** | `Enum<'insert' \| 'update' \| 'delete'>[]` | optional | Validation contexts | +| **tags** | `string[]` | optional | Categorization tags (e.g., "compliance", "billing") | +| **severity** | `Enum<'error' \| 'warning' \| 'info'>` | optional | | +| **message** | `string` | ✅ | Error message to display to the user | +| **type** | `string` | ✅ | | +| **fields** | `string[]` | ✅ | Fields that must be combined unique | +| **scope** | `string` | optional | Formula condition for scope (e.g. active = true) | +| **caseSensitive** | `boolean` | optional | | + +--- + +## ValidationRule + diff --git a/content/docs/references/data/validation/AsyncValidation.mdx b/content/docs/references/data/validation/AsyncValidation.mdx deleted file mode 100644 index 07a921950..000000000 --- a/content/docs/references/data/validation/AsyncValidation.mdx +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: AsyncValidation -description: AsyncValidation Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Unique rule name (snake_case) | -| **label** | `string` | optional | Human-readable label for the rule listing | -| **description** | `string` | optional | Administrative notes explaining the business reason | -| **active** | `boolean` | optional | | -| **events** | `Enum<'insert' \| 'update' \| 'delete'>[]` | optional | Validation contexts | -| **tags** | `string[]` | optional | Categorization tags (e.g., "compliance", "billing") | -| **severity** | `Enum<'error' \| 'warning' \| 'info'>` | optional | | -| **message** | `string` | ✅ | Error message to display to the user | -| **type** | `string` | ✅ | | -| **field** | `string` | ✅ | Field to validate | -| **validatorUrl** | `string` | optional | External API endpoint for validation | -| **method** | `Enum<'GET' \| 'POST'>` | optional | HTTP method for external call | -| **headers** | `Record` | optional | Custom headers for the request | -| **validatorFunction** | `string` | optional | Reference to custom validator function | -| **timeout** | `number` | optional | Timeout in milliseconds | -| **debounce** | `number` | optional | Debounce delay in milliseconds | -| **params** | `Record` | optional | Additional parameters to pass to validator | diff --git a/content/docs/references/data/validation/ConditionalValidation.mdx b/content/docs/references/data/validation/ConditionalValidation.mdx deleted file mode 100644 index 663670772..000000000 --- a/content/docs/references/data/validation/ConditionalValidation.mdx +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: ConditionalValidation -description: ConditionalValidation Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Unique rule name (snake_case) | -| **label** | `string` | optional | Human-readable label for the rule listing | -| **description** | `string` | optional | Administrative notes explaining the business reason | -| **active** | `boolean` | optional | | -| **events** | `Enum<'insert' \| 'update' \| 'delete'>[]` | optional | Validation contexts | -| **tags** | `string[]` | optional | Categorization tags (e.g., "compliance", "billing") | -| **severity** | `Enum<'error' \| 'warning' \| 'info'>` | optional | | -| **message** | `string` | ✅ | Error message to display to the user | -| **type** | `string` | ✅ | | -| **when** | `string` | ✅ | Condition formula (e.g. "type = 'enterprise'") | -| **then** | `object \| object \| object \| object \| object \| object \| object \| object \| any` | ✅ | Validation rule to apply when condition is true | -| **otherwise** | `object \| object \| object \| object \| object \| object \| object \| object \| any` | optional | Validation rule to apply when condition is false | diff --git a/content/docs/references/data/validation/CrossFieldValidation.mdx b/content/docs/references/data/validation/CrossFieldValidation.mdx deleted file mode 100644 index 9e55e2149..000000000 --- a/content/docs/references/data/validation/CrossFieldValidation.mdx +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: CrossFieldValidation -description: CrossFieldValidation Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Unique rule name (snake_case) | -| **label** | `string` | optional | Human-readable label for the rule listing | -| **description** | `string` | optional | Administrative notes explaining the business reason | -| **active** | `boolean` | optional | | -| **events** | `Enum<'insert' \| 'update' \| 'delete'>[]` | optional | Validation contexts | -| **tags** | `string[]` | optional | Categorization tags (e.g., "compliance", "billing") | -| **severity** | `Enum<'error' \| 'warning' \| 'info'>` | optional | | -| **message** | `string` | ✅ | Error message to display to the user | -| **type** | `string` | ✅ | | -| **condition** | `string` | ✅ | Formula expression comparing fields (e.g. "end_date > start_date") | -| **fields** | `string[]` | ✅ | Fields involved in the validation | diff --git a/content/docs/references/data/validation/CustomValidator.mdx b/content/docs/references/data/validation/CustomValidator.mdx deleted file mode 100644 index b373f0a9e..000000000 --- a/content/docs/references/data/validation/CustomValidator.mdx +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: CustomValidator -description: CustomValidator Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Unique rule name (snake_case) | -| **label** | `string` | optional | Human-readable label for the rule listing | -| **description** | `string` | optional | Administrative notes explaining the business reason | -| **active** | `boolean` | optional | | -| **events** | `Enum<'insert' \| 'update' \| 'delete'>[]` | optional | Validation contexts | -| **tags** | `string[]` | optional | Categorization tags (e.g., "compliance", "billing") | -| **severity** | `Enum<'error' \| 'warning' \| 'info'>` | optional | | -| **message** | `string` | ✅ | Error message to display to the user | -| **type** | `string` | ✅ | | -| **handler** | `string` | ✅ | Name of the custom validation function registered in the system | -| **params** | `Record` | optional | Parameters passed to the custom handler | diff --git a/content/docs/references/data/validation/FormatValidation.mdx b/content/docs/references/data/validation/FormatValidation.mdx deleted file mode 100644 index 2cb09badc..000000000 --- a/content/docs/references/data/validation/FormatValidation.mdx +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: FormatValidation -description: FormatValidation Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Unique rule name (snake_case) | -| **label** | `string` | optional | Human-readable label for the rule listing | -| **description** | `string` | optional | Administrative notes explaining the business reason | -| **active** | `boolean` | optional | | -| **events** | `Enum<'insert' \| 'update' \| 'delete'>[]` | optional | Validation contexts | -| **tags** | `string[]` | optional | Categorization tags (e.g., "compliance", "billing") | -| **severity** | `Enum<'error' \| 'warning' \| 'info'>` | optional | | -| **message** | `string` | ✅ | Error message to display to the user | -| **type** | `string` | ✅ | | -| **field** | `string` | ✅ | | -| **regex** | `string` | optional | | -| **format** | `Enum<'email' \| 'url' \| 'phone' \| 'json'>` | optional | | diff --git a/content/docs/references/data/validation/JSONValidation.mdx b/content/docs/references/data/validation/JSONValidation.mdx deleted file mode 100644 index e8d3ce100..000000000 --- a/content/docs/references/data/validation/JSONValidation.mdx +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: JSONValidation -description: JSONValidation Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Unique rule name (snake_case) | -| **label** | `string` | optional | Human-readable label for the rule listing | -| **description** | `string` | optional | Administrative notes explaining the business reason | -| **active** | `boolean` | optional | | -| **events** | `Enum<'insert' \| 'update' \| 'delete'>[]` | optional | Validation contexts | -| **tags** | `string[]` | optional | Categorization tags (e.g., "compliance", "billing") | -| **severity** | `Enum<'error' \| 'warning' \| 'info'>` | optional | | -| **message** | `string` | ✅ | Error message to display to the user | -| **type** | `string` | ✅ | | -| **field** | `string` | ✅ | JSON field to validate | -| **schema** | `Record` | ✅ | JSON Schema object definition | diff --git a/content/docs/references/data/validation/ScriptValidation.mdx b/content/docs/references/data/validation/ScriptValidation.mdx deleted file mode 100644 index 8331642bb..000000000 --- a/content/docs/references/data/validation/ScriptValidation.mdx +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: ScriptValidation -description: ScriptValidation Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Unique rule name (snake_case) | -| **label** | `string` | optional | Human-readable label for the rule listing | -| **description** | `string` | optional | Administrative notes explaining the business reason | -| **active** | `boolean` | optional | | -| **events** | `Enum<'insert' \| 'update' \| 'delete'>[]` | optional | Validation contexts | -| **tags** | `string[]` | optional | Categorization tags (e.g., "compliance", "billing") | -| **severity** | `Enum<'error' \| 'warning' \| 'info'>` | optional | | -| **message** | `string` | ✅ | Error message to display to the user | -| **type** | `string` | ✅ | | -| **condition** | `string` | ✅ | Formula expression. If TRUE, validation fails. (e.g. amount < 0) | diff --git a/content/docs/references/data/validation/StateMachineValidation.mdx b/content/docs/references/data/validation/StateMachineValidation.mdx deleted file mode 100644 index c5e6c835f..000000000 --- a/content/docs/references/data/validation/StateMachineValidation.mdx +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: StateMachineValidation -description: StateMachineValidation Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Unique rule name (snake_case) | -| **label** | `string` | optional | Human-readable label for the rule listing | -| **description** | `string` | optional | Administrative notes explaining the business reason | -| **active** | `boolean` | optional | | -| **events** | `Enum<'insert' \| 'update' \| 'delete'>[]` | optional | Validation contexts | -| **tags** | `string[]` | optional | Categorization tags (e.g., "compliance", "billing") | -| **severity** | `Enum<'error' \| 'warning' \| 'info'>` | optional | | -| **message** | `string` | ✅ | Error message to display to the user | -| **type** | `string` | ✅ | | -| **field** | `string` | ✅ | State field (e.g. status) | -| **transitions** | `Record` | ✅ | Map of `{ OldState: [AllowedNewStates] }` | diff --git a/content/docs/references/data/validation/UniquenessValidation.mdx b/content/docs/references/data/validation/UniquenessValidation.mdx deleted file mode 100644 index 4c5f80c7c..000000000 --- a/content/docs/references/data/validation/UniquenessValidation.mdx +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: UniquenessValidation -description: UniquenessValidation Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Unique rule name (snake_case) | -| **label** | `string` | optional | Human-readable label for the rule listing | -| **description** | `string` | optional | Administrative notes explaining the business reason | -| **active** | `boolean` | optional | | -| **events** | `Enum<'insert' \| 'update' \| 'delete'>[]` | optional | Validation contexts | -| **tags** | `string[]` | optional | Categorization tags (e.g., "compliance", "billing") | -| **severity** | `Enum<'error' \| 'warning' \| 'info'>` | optional | | -| **message** | `string` | ✅ | Error message to display to the user | -| **type** | `string` | ✅ | | -| **fields** | `string[]` | ✅ | Fields that must be combined unique | -| **scope** | `string` | optional | Formula condition for scope (e.g. active = true) | -| **caseSensitive** | `boolean` | optional | | diff --git a/content/docs/references/data/validation/ValidationRule.mdx b/content/docs/references/data/validation/ValidationRule.mdx deleted file mode 100644 index 8acc0ff10..000000000 --- a/content/docs/references/data/validation/ValidationRule.mdx +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: ValidationRule -description: ValidationRule Schema Reference ---- - diff --git a/content/docs/references/data/validation/meta.json b/content/docs/references/data/validation/meta.json deleted file mode 100644 index 8ef4e45b2..000000000 --- a/content/docs/references/data/validation/meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "title": "Validation" -} \ No newline at end of file diff --git a/content/docs/references/hub/composer.mdx b/content/docs/references/hub/composer.mdx new file mode 100644 index 000000000..089e9a160 --- /dev/null +++ b/content/docs/references/hub/composer.mdx @@ -0,0 +1,90 @@ +--- +title: Composer +description: Composer protocol schemas +--- + +# Composer + + +**Source:** `packages/spec/src/hub/composer.zod.ts` + + +## TypeScript Usage + +```typescript +import { BillOfMaterialsSchema, ComposerRequestSchema, ComposerResponseSchema, ConflictReportSchema, DependencyRequirementSchema } from '@objectstack/spec/hub'; +import type { BillOfMaterials, ComposerRequest, ComposerResponse, ConflictReport, DependencyRequirement } from '@objectstack/spec/hub'; + +// Validate data +const result = BillOfMaterialsSchema.parse(data); +``` + +--- + +## BillOfMaterials + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **tenantId** | `string` | ✅ | Target Tenant ID | +| **dependencies** | `object[]` | ✅ | Installed packages | +| **environment** | `Record` | optional | | +| **resolutionStrategy** | `Enum<'strict' \| 'override' \| 'merge'>` | optional | Conflict resolution strategy (strict=fail, override=last-wins, merge=deep-merge) | + +--- + +## ComposerRequest + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **bom** | `object` | ✅ | | +| **runtimeVersion** | `string` | optional | | +| **dryRun** | `boolean` | optional | | + +--- + +## ComposerResponse + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **success** | `boolean` | ✅ | | +| **manifest** | `object` | optional | The compiled System Manifest | +| **manifestUrl** | `string` | optional | Presigned download URL | +| **buildId** | `string` | ✅ | | +| **timestamp** | `string` | ✅ | | +| **duration** | `number` | ✅ | Compilation time in ms | +| **conflicts** | `object[]` | optional | | +| **errors** | `string[]` | optional | | + +--- + +## ConflictReport + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **resourceType** | `Enum<'object' \| 'field' \| 'api' \| 'ui'>` | ✅ | Type of colliding resource | +| **resourceId** | `string` | ✅ | ID of the resource | +| **sources** | `string[]` | ✅ | List of plugin IDs defining this resource | +| **resolution** | `string` | ✅ | How it was resolved (e.g. "com.example.erp won") | +| **severity** | `Enum<'info' \| 'warning' \| 'error'>` | ✅ | Severity of the conflict | + +--- + +## DependencyRequirement + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | ✅ | Plugin ID (e.g. "com.example.crm") | +| **version** | `string` | optional | SemVer range or "latest" | +| **configuration** | `Record` | optional | Configuration overrides | +| **features** | `Record` | optional | Feature toggles | + diff --git a/content/docs/references/hub/composer/BillOfMaterials.mdx b/content/docs/references/hub/composer/BillOfMaterials.mdx deleted file mode 100644 index dc046e80b..000000000 --- a/content/docs/references/hub/composer/BillOfMaterials.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: BillOfMaterials -description: BillOfMaterials Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **tenantId** | `string` | ✅ | Target Tenant ID | -| **dependencies** | `object[]` | ✅ | Installed packages | -| **environment** | `Record` | optional | | -| **resolutionStrategy** | `Enum<'strict' \| 'override' \| 'merge'>` | optional | Conflict resolution strategy (strict=fail, override=last-wins, merge=deep-merge) | diff --git a/content/docs/references/hub/composer/ComposerRequest.mdx b/content/docs/references/hub/composer/ComposerRequest.mdx deleted file mode 100644 index f69a711bf..000000000 --- a/content/docs/references/hub/composer/ComposerRequest.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: ComposerRequest -description: ComposerRequest Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **bom** | `object` | ✅ | | -| **runtimeVersion** | `string` | optional | | -| **dryRun** | `boolean` | optional | | diff --git a/content/docs/references/hub/composer/ComposerResponse.mdx b/content/docs/references/hub/composer/ComposerResponse.mdx deleted file mode 100644 index 97d4b5ed9..000000000 --- a/content/docs/references/hub/composer/ComposerResponse.mdx +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: ComposerResponse -description: ComposerResponse Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **success** | `boolean` | ✅ | | -| **manifest** | `object` | optional | The compiled System Manifest | -| **manifestUrl** | `string` | optional | Presigned download URL | -| **buildId** | `string` | ✅ | | -| **timestamp** | `string` | ✅ | | -| **duration** | `number` | ✅ | Compilation time in ms | -| **conflicts** | `object[]` | optional | | -| **errors** | `string[]` | optional | | diff --git a/content/docs/references/hub/composer/ConflictReport.mdx b/content/docs/references/hub/composer/ConflictReport.mdx deleted file mode 100644 index 8f9f89c24..000000000 --- a/content/docs/references/hub/composer/ConflictReport.mdx +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: ConflictReport -description: ConflictReport Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **resourceType** | `Enum<'object' \| 'field' \| 'api' \| 'ui'>` | ✅ | Type of colliding resource | -| **resourceId** | `string` | ✅ | ID of the resource | -| **sources** | `string[]` | ✅ | List of plugin IDs defining this resource | -| **resolution** | `string` | ✅ | How it was resolved (e.g. "com.example.erp won") | -| **severity** | `Enum<'info' \| 'warning' \| 'error'>` | ✅ | Severity of the conflict | diff --git a/content/docs/references/hub/composer/DependencyRequirement.mdx b/content/docs/references/hub/composer/DependencyRequirement.mdx deleted file mode 100644 index e47f0a732..000000000 --- a/content/docs/references/hub/composer/DependencyRequirement.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: DependencyRequirement -description: DependencyRequirement Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Plugin ID (e.g. "com.example.crm") | -| **version** | `string` | optional | SemVer range or "latest" | -| **configuration** | `Record` | optional | Configuration overrides | -| **features** | `Record` | optional | Feature toggles | diff --git a/content/docs/references/hub/composer/meta.json b/content/docs/references/hub/composer/meta.json deleted file mode 100644 index 92983b39a..000000000 --- a/content/docs/references/hub/composer/meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "title": "Composer" -} \ No newline at end of file diff --git a/content/docs/references/hub/index.mdx b/content/docs/references/hub/index.mdx new file mode 100644 index 000000000..a2bcf34f2 --- /dev/null +++ b/content/docs/references/hub/index.mdx @@ -0,0 +1,17 @@ +--- +title: Hub Protocol Overview +description: Complete reference for all hub protocol schemas +--- + +# Hub Protocol + +This section contains all protocol schemas for the hub layer of ObjectStack. + + + + + + + + + diff --git a/content/docs/references/hub/license.mdx b/content/docs/references/hub/license.mdx new file mode 100644 index 000000000..d91295909 --- /dev/null +++ b/content/docs/references/hub/license.mdx @@ -0,0 +1,81 @@ +--- +title: License +description: License protocol schemas +--- + +# License + + +**Source:** `packages/spec/src/hub/license.zod.ts` + + +## TypeScript Usage + +```typescript +import { FeatureSchema, LicenseSchema, MetricTypeSchema, PlanSchema } from '@objectstack/spec/hub'; +import type { Feature, License, MetricType, Plan } from '@objectstack/spec/hub'; + +// Validate data +const result = FeatureSchema.parse(data); +``` + +--- + +## Feature + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **code** | `string` | ✅ | Feature code (e.g. core.api_access) | +| **label** | `string` | ✅ | | +| **description** | `string` | optional | | +| **type** | `Enum<'boolean' \| 'counter' \| 'gauge'>` | optional | | +| **unit** | `Enum<'count' \| 'bytes' \| 'seconds' \| 'percent'>` | optional | | +| **requires** | `string[]` | optional | | + +--- + +## License + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **spaceId** | `string` | ✅ | Target Space ID | +| **planCode** | `string` | ✅ | | +| **issuedAt** | `string` | ✅ | | +| **expiresAt** | `string` | optional | | +| **status** | `Enum<'active' \| 'expired' \| 'suspended' \| 'trial'>` | ✅ | | +| **customFeatures** | `string[]` | optional | | +| **customLimits** | `Record` | optional | | +| **plugins** | `string[]` | optional | List of enabled plugin package IDs | +| **signature** | `string` | optional | Cryptographic signature of the license | + +--- + +## MetricType + +### Allowed Values + +* `boolean` +* `counter` +* `gauge` + +--- + +## Plan + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **code** | `string` | ✅ | Plan code (e.g. pro_v1) | +| **label** | `string` | ✅ | | +| **active** | `boolean` | optional | | +| **features** | `string[]` | ✅ | List of enabled boolean features | +| **limits** | `Record` | ✅ | Map of metric codes to limit values (e.g. `{ storage_gb: 10 }`) | +| **currency** | `string` | optional | | +| **priceMonthly** | `number` | optional | | +| **priceYearly** | `number` | optional | | + diff --git a/content/docs/references/hub/license/Feature.mdx b/content/docs/references/hub/license/Feature.mdx deleted file mode 100644 index 3a480aa1f..000000000 --- a/content/docs/references/hub/license/Feature.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: Feature -description: Feature Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **code** | `string` | ✅ | Feature code (e.g. core.api_access) | -| **label** | `string` | ✅ | | -| **description** | `string` | optional | | -| **type** | `Enum<'boolean' \| 'counter' \| 'gauge'>` | optional | | -| **unit** | `Enum<'count' \| 'bytes' \| 'seconds' \| 'percent'>` | optional | | -| **requires** | `string[]` | optional | | diff --git a/content/docs/references/hub/license/License.mdx b/content/docs/references/hub/license/License.mdx deleted file mode 100644 index 4b987bbaf..000000000 --- a/content/docs/references/hub/license/License.mdx +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: License -description: License Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **spaceId** | `string` | ✅ | Target Space ID | -| **planCode** | `string` | ✅ | | -| **issuedAt** | `string` | ✅ | | -| **expiresAt** | `string` | optional | | -| **status** | `Enum<'active' \| 'expired' \| 'suspended' \| 'trial'>` | ✅ | | -| **customFeatures** | `string[]` | optional | | -| **customLimits** | `Record` | optional | | -| **plugins** | `string[]` | optional | List of enabled plugin package IDs | -| **signature** | `string` | optional | Cryptographic signature of the license | diff --git a/content/docs/references/hub/license/MetricType.mdx b/content/docs/references/hub/license/MetricType.mdx deleted file mode 100644 index eae9b632e..000000000 --- a/content/docs/references/hub/license/MetricType.mdx +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: MetricType -description: MetricType Schema Reference ---- - -## Allowed Values - -* `boolean` -* `counter` -* `gauge` \ No newline at end of file diff --git a/content/docs/references/hub/license/Plan.mdx b/content/docs/references/hub/license/Plan.mdx deleted file mode 100644 index 516b7b8a2..000000000 --- a/content/docs/references/hub/license/Plan.mdx +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: Plan -description: Plan Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **code** | `string` | ✅ | Plan code (e.g. pro_v1) | -| **label** | `string` | ✅ | | -| **active** | `boolean` | optional | | -| **features** | `string[]` | ✅ | List of enabled boolean features | -| **limits** | `Record` | ✅ | Map of metric codes to limit values (e.g. `{ storage_gb: 10 }`) | -| **currency** | `string` | optional | | -| **priceMonthly** | `number` | optional | | -| **priceYearly** | `number` | optional | | diff --git a/content/docs/references/hub/license/meta.json b/content/docs/references/hub/license/meta.json deleted file mode 100644 index a27b22f95..000000000 --- a/content/docs/references/hub/license/meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "title": "License" -} \ No newline at end of file diff --git a/content/docs/references/hub/marketplace.mdx b/content/docs/references/hub/marketplace.mdx new file mode 100644 index 000000000..ebebeb7bf --- /dev/null +++ b/content/docs/references/hub/marketplace.mdx @@ -0,0 +1,73 @@ +--- +title: Marketplace +description: Marketplace protocol schemas +--- + +# Marketplace + + +**Source:** `packages/spec/src/hub/marketplace.zod.ts` + + +## TypeScript Usage + +```typescript +import { MarketplacePluginSchema, PluginAuthorSchema, PluginPricingSchema } from '@objectstack/spec/hub'; +import type { MarketplacePlugin, PluginAuthor, PluginPricing } from '@objectstack/spec/hub'; + +// Validate data +const result = MarketplacePluginSchema.parse(data); +``` + +--- + +## MarketplacePlugin + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | ✅ | | +| **label** | `string` | ✅ | | +| **description** | `string` | optional | | +| **readme** | `string` | optional | | +| **version** | `string` | ✅ | | +| **author** | `object` | optional | | +| **tags** | `string[]` | optional | | +| **category** | `Enum<'app' \| 'integration' \| 'theme' \| 'utility' \| 'driver'>` | optional | | +| **icon** | `string` | optional | | +| **screenshots** | `string[]` | optional | | +| **homepage** | `string` | optional | | +| **repository** | `string` | optional | | +| **bugs** | `string` | optional | | +| **downloads** | `integer` | optional | | +| **rating** | `number` | optional | | +| **pricing** | `object` | optional | | +| **verified** | `boolean` | optional | Is verified maintaned by ObjectStack | + +--- + +## PluginAuthor + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | | +| **email** | `string` | optional | | +| **url** | `string` | optional | | + +--- + +## PluginPricing + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **type** | `Enum<'free' \| 'one_time' \| 'recurring'>` | ✅ | | +| **currency** | `string` | optional | | +| **amount** | `number` | ✅ | | +| **interval** | `Enum<'month' \| 'year'>` | optional | Required if type is recurring | +| **trialDays** | `integer` | optional | | + diff --git a/content/docs/references/hub/marketplace/MarketplacePlugin.mdx b/content/docs/references/hub/marketplace/MarketplacePlugin.mdx deleted file mode 100644 index a12868ca7..000000000 --- a/content/docs/references/hub/marketplace/MarketplacePlugin.mdx +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: MarketplacePlugin -description: MarketplacePlugin Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | | -| **label** | `string` | ✅ | | -| **description** | `string` | optional | | -| **readme** | `string` | optional | | -| **version** | `string` | ✅ | | -| **author** | `object` | optional | | -| **tags** | `string[]` | optional | | -| **category** | `Enum<'app' \| 'integration' \| 'theme' \| 'utility' \| 'driver'>` | optional | | -| **icon** | `string` | optional | | -| **screenshots** | `string[]` | optional | | -| **homepage** | `string` | optional | | -| **repository** | `string` | optional | | -| **bugs** | `string` | optional | | -| **downloads** | `integer` | optional | | -| **rating** | `number` | optional | | -| **pricing** | `object` | optional | | -| **verified** | `boolean` | optional | Is verified maintaned by ObjectStack | diff --git a/content/docs/references/hub/marketplace/PluginAuthor.mdx b/content/docs/references/hub/marketplace/PluginAuthor.mdx deleted file mode 100644 index 220bac02d..000000000 --- a/content/docs/references/hub/marketplace/PluginAuthor.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: PluginAuthor -description: PluginAuthor Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | | -| **email** | `string` | optional | | -| **url** | `string` | optional | | diff --git a/content/docs/references/hub/marketplace/PluginPricing.mdx b/content/docs/references/hub/marketplace/PluginPricing.mdx deleted file mode 100644 index 91ef36b3e..000000000 --- a/content/docs/references/hub/marketplace/PluginPricing.mdx +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: PluginPricing -description: PluginPricing Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `Enum<'free' \| 'one_time' \| 'recurring'>` | ✅ | | -| **currency** | `string` | optional | | -| **amount** | `number` | ✅ | | -| **interval** | `Enum<'month' \| 'year'>` | optional | Required if type is recurring | -| **trialDays** | `integer` | optional | | diff --git a/content/docs/references/hub/marketplace/meta.json b/content/docs/references/hub/marketplace/meta.json deleted file mode 100644 index 8beddadc3..000000000 --- a/content/docs/references/hub/marketplace/meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "title": "Marketplace" -} \ No newline at end of file diff --git a/content/docs/references/hub/space.mdx b/content/docs/references/hub/space.mdx new file mode 100644 index 000000000..7c6311eca --- /dev/null +++ b/content/docs/references/hub/space.mdx @@ -0,0 +1,82 @@ +--- +title: Space +description: Space protocol schemas +--- + +# Space + + +**Source:** `packages/spec/src/hub/space.zod.ts` + + +## TypeScript Usage + +```typescript +import { DeploymentTargetSchema, HubSpaceSchema, SpaceSubscriptionSchema, SubscriptionStatusSchema } from '@objectstack/spec/hub'; +import type { DeploymentTarget, HubSpace, SpaceSubscription, SubscriptionStatus } from '@objectstack/spec/hub'; + +// Validate data +const result = DeploymentTargetSchema.parse(data); +``` + +--- + +## DeploymentTarget + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **provider** | `Enum<'vercel' \| 'docker' \| 'kubernetes'>` | ✅ | | +| **region** | `string` | optional | | +| **url** | `string` | optional | Public Access URL | +| **env** | `Record` | optional | Runtime Environment Variables | + +--- + +## HubSpace + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | ✅ | | +| **name** | `string` | ✅ | | +| **slug** | `string` | ✅ | URL friendly identifier | +| **ownerId** | `string` | ✅ | | +| **runtime** | `object` | optional | Runtime instance configuration | +| **bom** | `object` | ✅ | | +| **lastBuild** | `object` | optional | | +| **subscription** | `object` | optional | | +| **deployment** | `object` | optional | | +| **createdAt** | `string` | ✅ | | +| **updatedAt** | `string` | ✅ | | + +--- + +## SpaceSubscription + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **planId** | `string` | ✅ | Reference to Plan Code | +| **status** | `Enum<'active' \| 'past_due' \| 'canceled' \| 'trialing' \| 'incomplete'>` | ✅ | | +| **currentPeriodEnd** | `string` | optional | | +| **stripeCustomerId** | `string` | optional | | +| **stripeSubscriptionId** | `string` | optional | | +| **addons** | `object[]` | optional | | +| **usage** | `Record` | optional | | + +--- + +## SubscriptionStatus + +### Allowed Values + +* `active` +* `past_due` +* `canceled` +* `trialing` +* `incomplete` + diff --git a/content/docs/references/hub/space/DeploymentTarget.mdx b/content/docs/references/hub/space/DeploymentTarget.mdx deleted file mode 100644 index 34e73ef9f..000000000 --- a/content/docs/references/hub/space/DeploymentTarget.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: DeploymentTarget -description: DeploymentTarget Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **provider** | `Enum<'vercel' \| 'docker' \| 'kubernetes'>` | ✅ | | -| **region** | `string` | optional | | -| **url** | `string` | optional | Public Access URL | -| **env** | `Record` | optional | Runtime Environment Variables | diff --git a/content/docs/references/hub/space/HubSpace.mdx b/content/docs/references/hub/space/HubSpace.mdx deleted file mode 100644 index 0e789b129..000000000 --- a/content/docs/references/hub/space/HubSpace.mdx +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: HubSpace -description: HubSpace Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | | -| **name** | `string` | ✅ | | -| **slug** | `string` | ✅ | URL friendly identifier | -| **ownerId** | `string` | ✅ | | -| **runtime** | `object` | optional | Runtime instance configuration | -| **bom** | `object` | ✅ | | -| **lastBuild** | `object` | optional | | -| **subscription** | `object` | optional | | -| **deployment** | `object` | optional | | -| **createdAt** | `string` | ✅ | | -| **updatedAt** | `string` | ✅ | | diff --git a/content/docs/references/hub/space/SpaceSubscription.mdx b/content/docs/references/hub/space/SpaceSubscription.mdx deleted file mode 100644 index 0e68c11b3..000000000 --- a/content/docs/references/hub/space/SpaceSubscription.mdx +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: SpaceSubscription -description: SpaceSubscription Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **planId** | `string` | ✅ | Reference to Plan Code | -| **status** | `Enum<'active' \| 'past_due' \| 'canceled' \| 'trialing' \| 'incomplete'>` | ✅ | | -| **currentPeriodEnd** | `string` | optional | | -| **stripeCustomerId** | `string` | optional | | -| **stripeSubscriptionId** | `string` | optional | | -| **addons** | `object[]` | optional | | -| **usage** | `Record` | optional | | diff --git a/content/docs/references/hub/space/SubscriptionStatus.mdx b/content/docs/references/hub/space/SubscriptionStatus.mdx deleted file mode 100644 index 8b8d01191..000000000 --- a/content/docs/references/hub/space/SubscriptionStatus.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: SubscriptionStatus -description: SubscriptionStatus Schema Reference ---- - -## Allowed Values - -* `active` -* `past_due` -* `canceled` -* `trialing` -* `incomplete` \ No newline at end of file diff --git a/content/docs/references/hub/space/meta.json b/content/docs/references/hub/space/meta.json deleted file mode 100644 index a7ea693af..000000000 --- a/content/docs/references/hub/space/meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "title": "Space" -} \ No newline at end of file diff --git a/content/docs/references/hub/tenant.mdx b/content/docs/references/hub/tenant.mdx new file mode 100644 index 000000000..5db39df9e --- /dev/null +++ b/content/docs/references/hub/tenant.mdx @@ -0,0 +1,112 @@ +--- +title: Tenant +description: Tenant protocol schemas +--- + +# Tenant + + +**Source:** `packages/spec/src/hub/tenant.zod.ts` + + +## TypeScript Usage + +```typescript +import { DatabaseLevelIsolationStrategySchema, LevelIsolationStrategySchemaSchema, RowLevelIsolationStrategySchema, TenantSchema, TenantIsolationConfigSchema, TenantIsolationLevelSchema, TenantQuotaSchema, TenantSecurityPolicySchema } from '@objectstack/spec/hub'; +import type { DatabaseLevelIsolationStrategy, LevelIsolationStrategySchema, RowLevelIsolationStrategy, Tenant, TenantIsolationConfig, TenantIsolationLevel, TenantQuota, TenantSecurityPolicy } from '@objectstack/spec/hub'; + +// Validate data +const result = DatabaseLevelIsolationStrategySchema.parse(data); +``` + +--- + +## DatabaseLevelIsolationStrategy + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **strategy** | `string` | ✅ | Database-level isolation strategy | +| **database** | `object` | optional | Database configuration | +| **connectionPool** | `object` | optional | Connection pool configuration | +| **backup** | `object` | optional | Backup configuration | +| **encryption** | `object` | optional | Encryption configuration | + +--- + +## LevelIsolationStrategySchema + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **strategy** | `string` | ✅ | Schema-level isolation strategy | +| **schema** | `object` | optional | Schema configuration | +| **migrations** | `object` | optional | Migration configuration | +| **performance** | `object` | optional | Performance settings | + +--- + +## RowLevelIsolationStrategy + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **strategy** | `string` | ✅ | Row-level isolation strategy | +| **database** | `object` | optional | Database configuration | +| **performance** | `object` | optional | Performance settings | + +--- + +## Tenant + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | ✅ | Unique tenant identifier | +| **name** | `string` | ✅ | Tenant display name | +| **isolationLevel** | `Enum<'shared_schema' \| 'isolated_schema' \| 'isolated_db'>` | ✅ | | +| **customizations** | `Record` | optional | Custom configuration values | +| **quotas** | `object` | optional | | + +--- + +## TenantIsolationConfig + +--- + +## TenantIsolationLevel + +### Allowed Values + +* `shared_schema` +* `isolated_schema` +* `isolated_db` + +--- + +## TenantQuota + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **maxUsers** | `integer` | optional | Maximum number of users | +| **maxStorage** | `integer` | optional | Maximum storage in bytes | +| **apiRateLimit** | `integer` | optional | API requests per minute | + +--- + +## TenantSecurityPolicy + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **encryption** | `object` | optional | Encryption requirements | +| **accessControl** | `object` | optional | Access control requirements | +| **compliance** | `object` | optional | Compliance requirements | + diff --git a/content/docs/references/hub/tenant/DatabaseLevelIsolationStrategy.mdx b/content/docs/references/hub/tenant/DatabaseLevelIsolationStrategy.mdx deleted file mode 100644 index 3e0d6ba8a..000000000 --- a/content/docs/references/hub/tenant/DatabaseLevelIsolationStrategy.mdx +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: DatabaseLevelIsolationStrategy -description: DatabaseLevelIsolationStrategy Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **strategy** | `string` | ✅ | Database-level isolation strategy | -| **database** | `object` | optional | Database configuration | -| **connectionPool** | `object` | optional | Connection pool configuration | -| **backup** | `object` | optional | Backup configuration | -| **encryption** | `object` | optional | Encryption configuration | diff --git a/content/docs/references/hub/tenant/LevelIsolationStrategySchema.mdx b/content/docs/references/hub/tenant/LevelIsolationStrategySchema.mdx deleted file mode 100644 index b7ebe9be3..000000000 --- a/content/docs/references/hub/tenant/LevelIsolationStrategySchema.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: LevelIsolationStrategySchema -description: LevelIsolationStrategySchema Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **strategy** | `string` | ✅ | Schema-level isolation strategy | -| **schema** | `object` | optional | Schema configuration | -| **migrations** | `object` | optional | Migration configuration | -| **performance** | `object` | optional | Performance settings | diff --git a/content/docs/references/hub/tenant/RowLevelIsolationStrategy.mdx b/content/docs/references/hub/tenant/RowLevelIsolationStrategy.mdx deleted file mode 100644 index e15a26aff..000000000 --- a/content/docs/references/hub/tenant/RowLevelIsolationStrategy.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: RowLevelIsolationStrategy -description: RowLevelIsolationStrategy Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **strategy** | `string` | ✅ | Row-level isolation strategy | -| **database** | `object` | optional | Database configuration | -| **performance** | `object` | optional | Performance settings | diff --git a/content/docs/references/hub/tenant/Tenant.mdx b/content/docs/references/hub/tenant/Tenant.mdx deleted file mode 100644 index 63b2241a6..000000000 --- a/content/docs/references/hub/tenant/Tenant.mdx +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: Tenant -description: Tenant Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Unique tenant identifier | -| **name** | `string` | ✅ | Tenant display name | -| **isolationLevel** | `Enum<'shared_schema' \| 'isolated_schema' \| 'isolated_db'>` | ✅ | | -| **customizations** | `Record` | optional | Custom configuration values | -| **quotas** | `object` | optional | | diff --git a/content/docs/references/hub/tenant/TenantIsolationConfig.mdx b/content/docs/references/hub/tenant/TenantIsolationConfig.mdx deleted file mode 100644 index 80a0beec7..000000000 --- a/content/docs/references/hub/tenant/TenantIsolationConfig.mdx +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: TenantIsolationConfig -description: TenantIsolationConfig Schema Reference ---- - diff --git a/content/docs/references/hub/tenant/TenantIsolationLevel.mdx b/content/docs/references/hub/tenant/TenantIsolationLevel.mdx deleted file mode 100644 index 74af0d0da..000000000 --- a/content/docs/references/hub/tenant/TenantIsolationLevel.mdx +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: TenantIsolationLevel -description: TenantIsolationLevel Schema Reference ---- - -## Allowed Values - -* `shared_schema` -* `isolated_schema` -* `isolated_db` \ No newline at end of file diff --git a/content/docs/references/hub/tenant/TenantQuota.mdx b/content/docs/references/hub/tenant/TenantQuota.mdx deleted file mode 100644 index f1eb79ae0..000000000 --- a/content/docs/references/hub/tenant/TenantQuota.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: TenantQuota -description: TenantQuota Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **maxUsers** | `integer` | optional | Maximum number of users | -| **maxStorage** | `integer` | optional | Maximum storage in bytes | -| **apiRateLimit** | `integer` | optional | API requests per minute | diff --git a/content/docs/references/hub/tenant/TenantSecurityPolicy.mdx b/content/docs/references/hub/tenant/TenantSecurityPolicy.mdx deleted file mode 100644 index 42a8fb480..000000000 --- a/content/docs/references/hub/tenant/TenantSecurityPolicy.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: TenantSecurityPolicy -description: TenantSecurityPolicy Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **encryption** | `object` | optional | Encryption requirements | -| **accessControl** | `object` | optional | Access control requirements | -| **compliance** | `object` | optional | Compliance requirements | diff --git a/content/docs/references/hub/tenant/meta.json b/content/docs/references/hub/tenant/meta.json deleted file mode 100644 index f3b2fd222..000000000 --- a/content/docs/references/hub/tenant/meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "title": "Tenant" -} \ No newline at end of file diff --git a/content/docs/references/meta.cn.json b/content/docs/references/meta.cn.json new file mode 100644 index 000000000..04e340bd9 --- /dev/null +++ b/content/docs/references/meta.cn.json @@ -0,0 +1,19 @@ +{ + "title": "协议参考", + "pages": [ + "quick-reference", + "protocol-map", + "---", + "data", + "ui", + "automation", + "system", + "permission", + "ai", + "api", + "driver", + "auth", + "hub", + "shared" + ] +} diff --git a/content/docs/references/permission/index.mdx b/content/docs/references/permission/index.mdx new file mode 100644 index 000000000..75cb1db05 --- /dev/null +++ b/content/docs/references/permission/index.mdx @@ -0,0 +1,16 @@ +--- +title: Permission Protocol Overview +description: Complete reference for all permission protocol schemas +--- + +# Permission Protocol + +This section contains all protocol schemas for the permission layer of ObjectStack. + + + + + + + + diff --git a/content/docs/references/permission/permission.mdx b/content/docs/references/permission/permission.mdx new file mode 100644 index 000000000..f60179db2 --- /dev/null +++ b/content/docs/references/permission/permission.mdx @@ -0,0 +1,65 @@ +--- +title: Permission +description: Permission protocol schemas +--- + +# Permission + + +**Source:** `packages/spec/src/permission/permission.zod.ts` + + +## TypeScript Usage + +```typescript +import { FieldPermissionSchema, ObjectPermissionSchema, PermissionSetSchema } from '@objectstack/spec/permission'; +import type { FieldPermission, ObjectPermission, PermissionSet } from '@objectstack/spec/permission'; + +// Validate data +const result = FieldPermissionSchema.parse(data); +``` + +--- + +## FieldPermission + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **readable** | `boolean` | optional | Field read access | +| **editable** | `boolean` | optional | Field edit access | + +--- + +## ObjectPermission + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **allowCreate** | `boolean` | optional | Create permission | +| **allowRead** | `boolean` | optional | Read permission | +| **allowEdit** | `boolean` | optional | Edit permission | +| **allowDelete** | `boolean` | optional | Delete permission | +| **allowTransfer** | `boolean` | optional | Change record ownership | +| **allowRestore** | `boolean` | optional | Restore from trash (Undelete) | +| **allowPurge** | `boolean` | optional | Permanently delete (Hard Delete/GDPR) | +| **viewAllRecords** | `boolean` | optional | View All Data (Bypass Sharing) | +| **modifyAllRecords** | `boolean` | optional | Modify All Data (Bypass Sharing) | + +--- + +## PermissionSet + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Permission set unique name (lowercase snake_case) | +| **label** | `string` | optional | Display label | +| **isProfile** | `boolean` | optional | Whether this is a user profile | +| **objects** | `Record` | ✅ | Entity permissions | +| **fields** | `Record` | optional | Field level security | +| **systemPermissions** | `string[]` | optional | System level capabilities | + diff --git a/content/docs/references/permission/permission/FieldPermission.mdx b/content/docs/references/permission/permission/FieldPermission.mdx deleted file mode 100644 index 61319166a..000000000 --- a/content/docs/references/permission/permission/FieldPermission.mdx +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: FieldPermission -description: FieldPermission Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **readable** | `boolean` | optional | Field read access | -| **editable** | `boolean` | optional | Field edit access | diff --git a/content/docs/references/permission/permission/ObjectPermission.mdx b/content/docs/references/permission/permission/ObjectPermission.mdx deleted file mode 100644 index 67c734862..000000000 --- a/content/docs/references/permission/permission/ObjectPermission.mdx +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: ObjectPermission -description: ObjectPermission Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **allowCreate** | `boolean` | optional | Create permission | -| **allowRead** | `boolean` | optional | Read permission | -| **allowEdit** | `boolean` | optional | Edit permission | -| **allowDelete** | `boolean` | optional | Delete permission | -| **allowTransfer** | `boolean` | optional | Change record ownership | -| **allowRestore** | `boolean` | optional | Restore from trash (Undelete) | -| **allowPurge** | `boolean` | optional | Permanently delete (Hard Delete/GDPR) | -| **viewAllRecords** | `boolean` | optional | View All Data (Bypass Sharing) | -| **modifyAllRecords** | `boolean` | optional | Modify All Data (Bypass Sharing) | diff --git a/content/docs/references/permission/permission/PermissionSet.mdx b/content/docs/references/permission/permission/PermissionSet.mdx deleted file mode 100644 index 017783e11..000000000 --- a/content/docs/references/permission/permission/PermissionSet.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: PermissionSet -description: PermissionSet Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Permission set unique name (lowercase snake_case) | -| **label** | `string` | optional | Display label | -| **isProfile** | `boolean` | optional | Whether this is a user profile | -| **objects** | `Record` | ✅ | Entity permissions | -| **fields** | `Record` | optional | Field level security | -| **systemPermissions** | `string[]` | optional | System level capabilities | diff --git a/content/docs/references/permission/permission/meta.json b/content/docs/references/permission/permission/meta.json deleted file mode 100644 index b5d4b6b2b..000000000 --- a/content/docs/references/permission/permission/meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "title": "Permission" -} \ No newline at end of file diff --git a/content/docs/references/permission/rls.mdx b/content/docs/references/permission/rls.mdx new file mode 100644 index 000000000..1b342f563 --- /dev/null +++ b/content/docs/references/permission/rls.mdx @@ -0,0 +1,100 @@ +--- +title: Rls +description: Rls protocol schemas +--- + +# Rls + + +**Source:** `packages/spec/src/permission/rls.zod.ts` + + +## TypeScript Usage + +```typescript +import { RLSConfigSchema, RLSEvaluationResultSchema, RLSOperationSchema, RLSUserContextSchema, RowLevelSecurityPolicySchema } from '@objectstack/spec/permission'; +import type { RLSConfig, RLSEvaluationResult, RLSOperation, RLSUserContext, RowLevelSecurityPolicy } from '@objectstack/spec/permission'; + +// Validate data +const result = RLSConfigSchema.parse(data); +``` + +--- + +## RLSConfig + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **enabled** | `boolean` | optional | Enable RLS enforcement globally | +| **defaultPolicy** | `Enum<'deny' \| 'allow'>` | optional | Default action when no policies match | +| **allowSuperuserBypass** | `boolean` | optional | Allow superusers to bypass RLS | +| **bypassRoles** | `string[]` | optional | Roles that bypass RLS (see all data) | +| **logEvaluations** | `boolean` | optional | Log RLS policy evaluations for debugging | +| **cacheResults** | `boolean` | optional | Cache RLS evaluation results | +| **cacheTtlSeconds** | `integer` | optional | Cache TTL in seconds | +| **prefetchUserContext** | `boolean` | optional | Pre-fetch user context for performance | + +--- + +## RLSEvaluationResult + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **policyName** | `string` | ✅ | Policy name | +| **granted** | `boolean` | ✅ | Whether access was granted | +| **durationMs** | `number` | optional | Evaluation duration in milliseconds | +| **error** | `string` | optional | Error message if evaluation failed | +| **usingResult** | `boolean` | optional | USING clause evaluation result | +| **checkResult** | `boolean` | optional | CHECK clause evaluation result | + +--- + +## RLSOperation + +### Allowed Values + +* `select` +* `insert` +* `update` +* `delete` +* `all` + +--- + +## RLSUserContext + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | ✅ | User ID | +| **email** | `string` | optional | User email | +| **tenantId** | `string` | optional | Tenant/Organization ID | +| **role** | `string \| string[]` | optional | User role(s) | +| **department** | `string` | optional | User department | +| **attributes** | `Record` | optional | Additional custom user attributes | + +--- + +## RowLevelSecurityPolicy + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Policy unique identifier (snake_case) | +| **label** | `string` | optional | Human-readable policy label | +| **description** | `string` | optional | Policy description and business justification | +| **object** | `string` | ✅ | Target object name | +| **operation** | `Enum<'select' \| 'insert' \| 'update' \| 'delete' \| 'all'>` | ✅ | Database operation this policy applies to | +| **using** | `string` | optional | Filter condition for SELECT/UPDATE/DELETE (PostgreSQL SQL WHERE clause syntax with parameterized context variables). Optional for INSERT-only policies. | +| **check** | `string` | optional | Validation condition for INSERT/UPDATE (defaults to USING clause if not specified - enforced at application level) | +| **roles** | `string[]` | optional | Roles this policy applies to (omit for all roles) | +| **enabled** | `boolean` | optional | Whether this policy is active | +| **priority** | `integer` | optional | Policy evaluation priority (higher = evaluated first) | +| **tags** | `string[]` | optional | Policy categorization tags | + diff --git a/content/docs/references/permission/rls/RLSConfig.mdx b/content/docs/references/permission/rls/RLSConfig.mdx deleted file mode 100644 index 2c55e7906..000000000 --- a/content/docs/references/permission/rls/RLSConfig.mdx +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: RLSConfig -description: RLSConfig Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | optional | Enable RLS enforcement globally | -| **defaultPolicy** | `Enum<'deny' \| 'allow'>` | optional | Default action when no policies match | -| **allowSuperuserBypass** | `boolean` | optional | Allow superusers to bypass RLS | -| **bypassRoles** | `string[]` | optional | Roles that bypass RLS (see all data) | -| **logEvaluations** | `boolean` | optional | Log RLS policy evaluations for debugging | -| **cacheResults** | `boolean` | optional | Cache RLS evaluation results | -| **cacheTtlSeconds** | `integer` | optional | Cache TTL in seconds | -| **prefetchUserContext** | `boolean` | optional | Pre-fetch user context for performance | diff --git a/content/docs/references/permission/rls/RLSEvaluationResult.mdx b/content/docs/references/permission/rls/RLSEvaluationResult.mdx deleted file mode 100644 index 092fbaed1..000000000 --- a/content/docs/references/permission/rls/RLSEvaluationResult.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: RLSEvaluationResult -description: RLSEvaluationResult Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **policyName** | `string` | ✅ | Policy name | -| **granted** | `boolean` | ✅ | Whether access was granted | -| **durationMs** | `number` | optional | Evaluation duration in milliseconds | -| **error** | `string` | optional | Error message if evaluation failed | -| **usingResult** | `boolean` | optional | USING clause evaluation result | -| **checkResult** | `boolean` | optional | CHECK clause evaluation result | diff --git a/content/docs/references/permission/rls/RLSOperation.mdx b/content/docs/references/permission/rls/RLSOperation.mdx deleted file mode 100644 index 327a10285..000000000 --- a/content/docs/references/permission/rls/RLSOperation.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: RLSOperation -description: RLSOperation Schema Reference ---- - -## Allowed Values - -* `select` -* `insert` -* `update` -* `delete` -* `all` \ No newline at end of file diff --git a/content/docs/references/permission/rls/RLSUserContext.mdx b/content/docs/references/permission/rls/RLSUserContext.mdx deleted file mode 100644 index 20649e6a3..000000000 --- a/content/docs/references/permission/rls/RLSUserContext.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: RLSUserContext -description: RLSUserContext Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | User ID | -| **email** | `string` | optional | User email | -| **tenantId** | `string` | optional | Tenant/Organization ID | -| **role** | `string \| string[]` | optional | User role(s) | -| **department** | `string` | optional | User department | -| **attributes** | `Record` | optional | Additional custom user attributes | diff --git a/content/docs/references/permission/rls/RowLevelSecurityPolicy.mdx b/content/docs/references/permission/rls/RowLevelSecurityPolicy.mdx deleted file mode 100644 index b73d798d2..000000000 --- a/content/docs/references/permission/rls/RowLevelSecurityPolicy.mdx +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: RowLevelSecurityPolicy -description: RowLevelSecurityPolicy Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Policy unique identifier (snake_case) | -| **label** | `string` | optional | Human-readable policy label | -| **description** | `string` | optional | Policy description and business justification | -| **object** | `string` | ✅ | Target object name | -| **operation** | `Enum<'select' \| 'insert' \| 'update' \| 'delete' \| 'all'>` | ✅ | Database operation this policy applies to | -| **using** | `string` | optional | Filter condition for SELECT/UPDATE/DELETE (PostgreSQL SQL WHERE clause syntax with parameterized context variables). Optional for INSERT-only policies. | -| **check** | `string` | optional | Validation condition for INSERT/UPDATE (defaults to USING clause if not specified - enforced at application level) | -| **roles** | `string[]` | optional | Roles this policy applies to (omit for all roles) | -| **enabled** | `boolean` | optional | Whether this policy is active | -| **priority** | `integer` | optional | Policy evaluation priority (higher = evaluated first) | -| **tags** | `string[]` | optional | Policy categorization tags | diff --git a/content/docs/references/permission/rls/meta.json b/content/docs/references/permission/rls/meta.json deleted file mode 100644 index 5a808ca2f..000000000 --- a/content/docs/references/permission/rls/meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "title": "Rls" -} \ No newline at end of file diff --git a/content/docs/references/permission/sharing.mdx b/content/docs/references/permission/sharing.mdx new file mode 100644 index 000000000..c3beba1d8 --- /dev/null +++ b/content/docs/references/permission/sharing.mdx @@ -0,0 +1,103 @@ +--- +title: Sharing +description: Sharing protocol schemas +--- + +# Sharing + + +**Source:** `packages/spec/src/permission/sharing.zod.ts` + + +## TypeScript Usage + +```typescript +import { CriteriaSharingRuleSchema, OWDModelSchema, OwnerSharingRuleSchema, ShareRecipientTypeSchema, SharingLevelSchema, SharingRuleSchema, SharingRuleTypeSchema } from '@objectstack/spec/permission'; +import type { CriteriaSharingRule, OWDModel, OwnerSharingRule, ShareRecipientType, SharingLevel, SharingRule, SharingRuleType } from '@objectstack/spec/permission'; + +// Validate data +const result = CriteriaSharingRuleSchema.parse(data); +``` + +--- + +## CriteriaSharingRule + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Unique rule name (snake_case) | +| **label** | `string` | optional | Human-readable label | +| **description** | `string` | optional | Administrative notes | +| **object** | `string` | ✅ | Target Object Name | +| **active** | `boolean` | optional | | +| **accessLevel** | `Enum<'read' \| 'edit' \| 'full'>` | optional | | +| **sharedWith** | `object` | ✅ | The recipient of the shared access | +| **type** | `string` | ✅ | | +| **condition** | `string` | ✅ | Formula condition (e.g. "department = 'Sales'") | + +--- + +## OWDModel + +### Allowed Values + +* `private` +* `public_read` +* `public_read_write` +* `controlled_by_parent` + +--- + +## OwnerSharingRule + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Unique rule name (snake_case) | +| **label** | `string` | optional | Human-readable label | +| **description** | `string` | optional | Administrative notes | +| **object** | `string` | ✅ | Target Object Name | +| **active** | `boolean` | optional | | +| **accessLevel** | `Enum<'read' \| 'edit' \| 'full'>` | optional | | +| **sharedWith** | `object` | ✅ | The recipient of the shared access | +| **type** | `string` | ✅ | | +| **ownedBy** | `object` | ✅ | Source group/role whose records are being shared | + +--- + +## ShareRecipientType + +### Allowed Values + +* `user` +* `group` +* `role` +* `role_and_subordinates` +* `guest` + +--- + +## SharingLevel + +### Allowed Values + +* `read` +* `edit` +* `full` + +--- + +## SharingRule + +--- + +## SharingRuleType + +### Allowed Values + +* `owner` +* `criteria` + diff --git a/content/docs/references/permission/sharing/CriteriaSharingRule.mdx b/content/docs/references/permission/sharing/CriteriaSharingRule.mdx deleted file mode 100644 index a4374d8e9..000000000 --- a/content/docs/references/permission/sharing/CriteriaSharingRule.mdx +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: CriteriaSharingRule -description: CriteriaSharingRule Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Unique rule name (snake_case) | -| **label** | `string` | optional | Human-readable label | -| **description** | `string` | optional | Administrative notes | -| **object** | `string` | ✅ | Target Object Name | -| **active** | `boolean` | optional | | -| **accessLevel** | `Enum<'read' \| 'edit' \| 'full'>` | optional | | -| **sharedWith** | `object` | ✅ | The recipient of the shared access | -| **type** | `string` | ✅ | | -| **condition** | `string` | ✅ | Formula condition (e.g. "department = 'Sales'") | diff --git a/content/docs/references/permission/sharing/OWDModel.mdx b/content/docs/references/permission/sharing/OWDModel.mdx deleted file mode 100644 index a6b676c1c..000000000 --- a/content/docs/references/permission/sharing/OWDModel.mdx +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: OWDModel -description: OWDModel Schema Reference ---- - -## Allowed Values - -* `private` -* `public_read` -* `public_read_write` -* `controlled_by_parent` \ No newline at end of file diff --git a/content/docs/references/permission/sharing/OwnerSharingRule.mdx b/content/docs/references/permission/sharing/OwnerSharingRule.mdx deleted file mode 100644 index dd3b69b98..000000000 --- a/content/docs/references/permission/sharing/OwnerSharingRule.mdx +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: OwnerSharingRule -description: OwnerSharingRule Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Unique rule name (snake_case) | -| **label** | `string` | optional | Human-readable label | -| **description** | `string` | optional | Administrative notes | -| **object** | `string` | ✅ | Target Object Name | -| **active** | `boolean` | optional | | -| **accessLevel** | `Enum<'read' \| 'edit' \| 'full'>` | optional | | -| **sharedWith** | `object` | ✅ | The recipient of the shared access | -| **type** | `string` | ✅ | | -| **ownedBy** | `object` | ✅ | Source group/role whose records are being shared | diff --git a/content/docs/references/permission/sharing/ShareRecipientType.mdx b/content/docs/references/permission/sharing/ShareRecipientType.mdx deleted file mode 100644 index 3790701ce..000000000 --- a/content/docs/references/permission/sharing/ShareRecipientType.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: ShareRecipientType -description: ShareRecipientType Schema Reference ---- - -## Allowed Values - -* `user` -* `group` -* `role` -* `role_and_subordinates` -* `guest` \ No newline at end of file diff --git a/content/docs/references/permission/sharing/SharingLevel.mdx b/content/docs/references/permission/sharing/SharingLevel.mdx deleted file mode 100644 index 1b013707b..000000000 --- a/content/docs/references/permission/sharing/SharingLevel.mdx +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: SharingLevel -description: SharingLevel Schema Reference ---- - -## Allowed Values - -* `read` -* `edit` -* `full` \ No newline at end of file diff --git a/content/docs/references/permission/sharing/SharingRule.mdx b/content/docs/references/permission/sharing/SharingRule.mdx deleted file mode 100644 index f0223b515..000000000 --- a/content/docs/references/permission/sharing/SharingRule.mdx +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: SharingRule -description: SharingRule Schema Reference ---- - diff --git a/content/docs/references/permission/sharing/SharingRuleType.mdx b/content/docs/references/permission/sharing/SharingRuleType.mdx deleted file mode 100644 index df297b610..000000000 --- a/content/docs/references/permission/sharing/SharingRuleType.mdx +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: SharingRuleType -description: SharingRuleType Schema Reference ---- - -## Allowed Values - -* `owner` -* `criteria` \ No newline at end of file diff --git a/content/docs/references/permission/sharing/meta.json b/content/docs/references/permission/sharing/meta.json deleted file mode 100644 index 49071aa3c..000000000 --- a/content/docs/references/permission/sharing/meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "title": "Sharing" -} \ No newline at end of file diff --git a/content/docs/references/permission/territory.mdx b/content/docs/references/permission/territory.mdx new file mode 100644 index 000000000..62cf01120 --- /dev/null +++ b/content/docs/references/permission/territory.mdx @@ -0,0 +1,64 @@ +--- +title: Territory +description: Territory protocol schemas +--- + +# Territory + + +**Source:** `packages/spec/src/permission/territory.zod.ts` + + +## TypeScript Usage + +```typescript +import { TerritorySchema, TerritoryModelSchema, TerritoryTypeSchema } from '@objectstack/spec/permission'; +import type { Territory, TerritoryModel, TerritoryType } from '@objectstack/spec/permission'; + +// Validate data +const result = TerritorySchema.parse(data); +``` + +--- + +## Territory + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Territory unique name (lowercase snake_case) | +| **label** | `string` | ✅ | Territory Label (e.g. "West Coast") | +| **modelId** | `string` | ✅ | Belongs to which Territory Model | +| **parent** | `string` | optional | Parent Territory | +| **type** | `Enum<'geography' \| 'industry' \| 'named_account' \| 'product_line'>` | optional | | +| **assignmentRule** | `string` | optional | Criteria based assignment rule | +| **assignedUsers** | `string[]` | optional | | +| **accountAccess** | `Enum<'read' \| 'edit'>` | optional | | +| **opportunityAccess** | `Enum<'read' \| 'edit'>` | optional | | +| **caseAccess** | `Enum<'read' \| 'edit'>` | optional | | + +--- + +## TerritoryModel + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Model Name (e.g. FY24 Planning) | +| **state** | `Enum<'planning' \| 'active' \| 'archived'>` | optional | | +| **startDate** | `string` | optional | | +| **endDate** | `string` | optional | | + +--- + +## TerritoryType + +### Allowed Values + +* `geography` +* `industry` +* `named_account` +* `product_line` + diff --git a/content/docs/references/permission/territory/Territory.mdx b/content/docs/references/permission/territory/Territory.mdx deleted file mode 100644 index 337ea7987..000000000 --- a/content/docs/references/permission/territory/Territory.mdx +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Territory -description: Territory Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Territory unique name (lowercase snake_case) | -| **label** | `string` | ✅ | Territory Label (e.g. "West Coast") | -| **modelId** | `string` | ✅ | Belongs to which Territory Model | -| **parent** | `string` | optional | Parent Territory | -| **type** | `Enum<'geography' \| 'industry' \| 'named_account' \| 'product_line'>` | optional | | -| **assignmentRule** | `string` | optional | Criteria based assignment rule | -| **assignedUsers** | `string[]` | optional | | -| **accountAccess** | `Enum<'read' \| 'edit'>` | optional | | -| **opportunityAccess** | `Enum<'read' \| 'edit'>` | optional | | -| **caseAccess** | `Enum<'read' \| 'edit'>` | optional | | diff --git a/content/docs/references/permission/territory/TerritoryModel.mdx b/content/docs/references/permission/territory/TerritoryModel.mdx deleted file mode 100644 index e043d74cb..000000000 --- a/content/docs/references/permission/territory/TerritoryModel.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: TerritoryModel -description: TerritoryModel Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Model Name (e.g. FY24 Planning) | -| **state** | `Enum<'planning' \| 'active' \| 'archived'>` | optional | | -| **startDate** | `string` | optional | | -| **endDate** | `string` | optional | | diff --git a/content/docs/references/permission/territory/TerritoryType.mdx b/content/docs/references/permission/territory/TerritoryType.mdx deleted file mode 100644 index d43de23a5..000000000 --- a/content/docs/references/permission/territory/TerritoryType.mdx +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: TerritoryType -description: TerritoryType Schema Reference ---- - -## Allowed Values - -* `geography` -* `industry` -* `named_account` -* `product_line` \ No newline at end of file diff --git a/content/docs/references/permission/territory/meta.json b/content/docs/references/permission/territory/meta.json deleted file mode 100644 index e87a9053e..000000000 --- a/content/docs/references/permission/territory/meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "title": "Territory" -} \ No newline at end of file diff --git a/content/docs/references/protocol-map.mdx b/content/docs/references/protocol-map.mdx new file mode 100644 index 000000000..e786a6354 --- /dev/null +++ b/content/docs/references/protocol-map.mdx @@ -0,0 +1,364 @@ +--- +title: Protocol Architecture Map +description: Visual guide to ObjectStack protocol relationships and dependencies +--- + + +# Protocol Architecture Map + +Understand how the 70 ObjectStack protocols fit together to form a complete business platform. + +## The Three-Layer Architecture + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ APPLICATION LAYER (User-Facing) │ +│ ┌──────────┐ ┌──────────┐ ┌───────────┐ ┌──────────┐ │ +│ │ Apps │ │ Pages │ │Dashboards │ │ Reports │ │ +│ └────┬─────┘ └────┬─────┘ └─────┬─────┘ └────┬─────┘ │ +│ └─────────────┴──────────────┴─────────────┘ │ +└────────────────────────────┬─────────────────────────────────────┘ + │ + ┌────────▼────────┐ + │ ObjectUI (UI) │ + │ 10 Protocols │ + └────────┬────────┘ + │ +┌────────────────────────────┴─────────────────────────────────────┐ +│ BUSINESS LOGIC LAYER │ +│ ┌──────────┐ ┌──────────┐ ┌───────────┐ ┌──────────┐ │ +│ │ Objects │ │ Fields │ │ Queries │ │ Rules │ │ +│ └────┬─────┘ └────┬─────┘ └─────┬─────┘ └────┬─────┘ │ +│ └─────────────┴──────────────┴─────────────┘ │ +└────────────────────────────┬─────────────────────────────────────┘ + │ + ┌────────▼────────┐ + │ ObjectQL (Data) │ + │ 8 Protocols │ + └────────┬────────┘ + │ +┌────────────────────────────┴─────────────────────────────────────┐ +│ RUNTIME INFRASTRUCTURE LAYER │ +│ ┌──────────┐ ┌──────────┐ ┌───────────┐ ┌──────────┐ │ +│ │ Drivers │ │ Events │ │ Auth │ │ APIs │ │ +│ └────┬─────┘ └────┬─────┘ └─────┬─────┘ └────┬─────┘ │ +│ └─────────────┴──────────────┴─────────────┘ │ +└────────────────────────────┬─────────────────────────────────────┘ + │ + ┌────────▼────────┐ + │ ObjectOS (Sys) │ + │ 40+ Protocols │ + └─────────────────┘ +``` + +## Protocol Dependencies + +### Core Foundation + +The foundation protocols that everything else builds upon: + + + + + + +### Layer 1: Data (ObjectQL) + +Data layer protocols define business logic and data structure. + +``` +Field Protocol (Core) + ↓ + ├→ Object Protocol (uses Fields) + ├→ Query Protocol (references Fields) + ├→ Filter Protocol (filters on Fields) + └→ Validation Protocol (validates Fields) + ↓ + └→ Hook Protocol (extends validation with code) +``` + +**Dependencies:** +- `Field` → No dependencies (foundational) +- `Object` → Depends on `Field`, `Validation` +- `Query` → Depends on `Filter`, `Object` +- `Validation` → Depends on `Field` + +### Layer 2: UI (ObjectUI) + +UI protocols build on top of data protocols. + +``` +Theme Protocol (Foundation) + ↓ +View Protocol (uses Object, Query) + ├→ ListView (uses Query, Filter) + ├→ FormView (uses Object, Field) + └→ Dashboard (uses View, Widget) + ↓ + ├→ Page Protocol (composes Views) + └→ App Protocol (organizes Pages) + ↓ + └→ Action Protocol (UI interactions) +``` + +**Dependencies:** +- `Theme` → No data dependencies +- `View` → Depends on `Object`, `Query`, `Filter` +- `Page` → Depends on `View`, `Component` +- `App` → Depends on `Page`, `Dashboard` +- `Action` → Depends on `Flow`, `Workflow` + +### Layer 3: System (ObjectOS) + +System protocols provide runtime infrastructure. + +``` +Driver Protocol (Database Abstraction) + ↓ +Datasource Protocol (Connection Config) + ↓ + ├→ Context Protocol (Runtime State) + ├→ Events Protocol (Event Bus) + └→ Plugin Protocol (Extensibility) + ↓ + ├→ Auth Protocol (Identity) + ├→ Permission Protocol (Access Control) + ├→ API Protocol (External Access) + └→ Automation Protocol (Workflows) + ↓ + └→ AI Protocol (Intelligence) +``` + +**Key Dependencies:** +- `Driver` → Foundation for all data access +- `Datasource` → Depends on `Driver` +- `Context` → Provides runtime state to all protocols +- `Auth` → Used by `Permission`, `API`, `Automation` +- `Permission` → Depends on `Auth`, `Object` + +## Cross-Protocol Relationships + +### Example: Building a CRM Contact Form + +Here's how multiple protocols work together: + +```typescript +// 1. DEFINE DATA (ObjectQL) +// File: objects/contact.object.yml +const contactObject = { + name: 'contact', // Object Protocol + fields: { // Field Protocol + email: { + type: 'email', + required: true, + validation: [ // Validation Protocol + { rule: 'email_format' } + ] + } + } +}; + +// 2. CREATE UI (ObjectUI) +// File: views/contact_form.view.yml +const contactForm = { + type: 'form', // View Protocol + object: 'contact', // References Object Protocol + layout: { // Page Protocol + sections: [ + { fields: ['email', 'phone'] } + ] + }, + theme: 'default' // Theme Protocol +}; + +// 3. ADD TO APP (ObjectUI) +// File: apps/crm.app.yml +const crmApp = { + name: 'crm', // App Protocol + navigation: [ // Navigation Items + { + type: 'object', + object: 'contact', + defaultView: 'contact_form' + } + ] +}; + +// 4. CONFIGURE ACCESS (Permission) +// File: permissions/contact.permission.yml +const contactPermission = { + object: 'contact', // Permission Protocol + roles: ['sales_rep'], // Auth Protocol + access: { + read: true, + create: true, + edit: true + } +}; + +// 5. ADD AUTOMATION (Automation) +// File: flows/welcome_email.flow.yml +const welcomeFlow = { + trigger: { // Flow Protocol + object: 'contact', + event: 'after_insert' + }, + actions: [ + { + type: 'email', // Action Protocol + template: 'welcome' + } + ] +}; +``` + +## Protocol Usage Patterns + +### Pattern 1: Data-Driven UI + +When UI is automatically generated from data definitions: + +``` +Object → Field → View → Page → App +``` + +**Example:** Auto-generated CRUD interfaces + +### Pattern 2: Custom UI with Data Binding + +When you build custom UI that connects to data: + +``` +Page → Component → View (Custom) → Query → Object +``` + +**Example:** Custom dashboard with data visualizations + +### Pattern 3: Automation & Integration + +When adding business logic automation: + +``` +Object → Hook → Flow → Automation → API/Webhook +``` + +**Example:** Lead assignment workflow with Slack notifications + +### Pattern 4: AI-Enhanced Applications + +When adding AI capabilities: + +``` +Object → RAG Pipeline → Agent → Conversation → UI +``` + +**Example:** AI-powered customer support chatbot + +## Protocol Categories by Responsibility + +### 🗄️ Data Definition +- **Primary:** Field, Object, Validation +- **Secondary:** Dataset, Mapping, Hook + +### 🔍 Data Access +- **Primary:** Query, Filter +- **Secondary:** Driver, Datasource + +### 🎨 Presentation +- **Primary:** View, Page, Theme +- **Secondary:** Component, Widget, Block + +### 🏗️ Application Structure +- **Primary:** App, Manifest +- **Secondary:** Plugin, Feature + +### 📊 Analytics & Reporting +- **Primary:** Report, Dashboard +- **Secondary:** Query (aggregations) + +### ⚙️ Automation +- **Primary:** Flow, Workflow +- **Secondary:** Approval, Webhook, ETL + +### 🔐 Security +- **Primary:** Auth, Permission +- **Secondary:** RLS, Sharing, Policy + +### 🌐 External Integration +- **Primary:** API, Connector +- **Secondary:** OData, Realtime, Webhook + +### 🤖 AI/ML +- **Primary:** Agent, RAG Pipeline +- **Secondary:** NLQ, Conversation, Model Registry + +## Common Integration Points + +### ObjectQL ↔ ObjectUI +```typescript +// UI consumes data definitions +const view: View = { + object: 'customer', // Reference to Object Protocol + fields: ['name', 'email'], // Reference to Field Protocol + filters: [...] // Reference to Filter Protocol +}; +``` + +### ObjectQL ↔ ObjectOS +```typescript +// Data is stored via system drivers +const datasource: Datasource = { + driver: 'postgres', // Reference to Driver Protocol + connection: {...} +}; + +const object: Object = { + name: 'customer', + datasource: 'primary' // Uses system datasource +}; +``` + +### ObjectUI ↔ ObjectOS +```typescript +// UI is secured via permission system +const app: App = { + navigation: [ + { + object: 'customer', + visible: 'hasPermission("customer", "read")' // References Permission + } + ] +}; +``` + +## Next Steps + + +Use this map as a reference when designing your application architecture. + + + + + + + diff --git a/content/docs/references/quick-reference.mdx b/content/docs/references/quick-reference.mdx new file mode 100644 index 000000000..48f8dcd86 --- /dev/null +++ b/content/docs/references/quick-reference.mdx @@ -0,0 +1,214 @@ +--- +title: Quick Reference Guide +description: Fast lookup table for all ObjectStack protocols +--- + + +# Quick Reference Guide + +Fast lookup for all 70 ObjectStack protocols organized by category. + + +Click on any protocol name to view its complete API reference. + + +## Data Protocol (8 protocols) + +Core business logic and data modeling schemas. + +| Protocol | Source File | Key Schemas | Purpose | +|:---------|:-----------|:------------|:--------| +| **[Field](./data/field)** | `field.zod.ts` | Field, FieldType, SelectOption | 44 field types for data modeling | +| **[Object](./data/object)** | `object.zod.ts` | Object, ObjectCapabilities | Object/table definitions | +| **[Query](./data/query)** | `query.zod.ts` | Query, QueryOptions | Query AST with joins, aggregations | +| **[Filter](./data/filter)** | `filter.zod.ts` | QueryFilter, FilterCondition | Advanced filtering operators | +| **[Validation](./data/validation)** | `validation.zod.ts` | ValidationRule | Business validation rules | +| **[Dataset](./data/dataset)** | `dataset.zod.ts` | Dataset, DatasetMode | Reusable dataset definitions | +| **[Mapping](./data/mapping)** | `mapping.zod.ts` | FieldMapping | Field transformation mappings | +| **[Hook](./data/hook)** | `hook.zod.ts` | Hook, HookEvent | Lifecycle event hooks | + +## UI Protocol (10 protocols) + +Presentation layer - views, forms, dashboards, and themes. + +| Protocol | Source File | Key Schemas | Purpose | +|:---------|:-----------|:------------|:--------| +| **[View](./ui/view)** | `view.zod.ts` | View, ListView, FormView | List and form view configurations | +| **[Page](./ui/page)** | `page.zod.ts` | Page, PageComponent | FlexiPage layouts | +| **[App](./ui/app)** | `app.zod.ts` | App, NavigationItem | Application navigation structure | +| **[Dashboard](./ui/dashboard)** | `dashboard.zod.ts` | Dashboard, DashboardWidget | Dashboard layouts and widgets | +| **[Report](./ui/report)** | `report.zod.ts` | Report, ReportType | Report definitions | +| **[Action](./ui/action)** | `action.zod.ts` | Action, ActionType | UI button actions | +| **[Component](./ui/component)** | `component.zod.ts` | PageComponent variants | Reusable UI components | +| **[Block](./ui/block)** | `block.zod.ts` | Block, BlockType | UI building blocks | +| **[Theme](./ui/theme)** | `theme.zod.ts` | Theme, ColorPalette | Theming and branding | +| **[Widget](./ui/widget)** | `widget.zod.ts` | WidgetManifest | Custom widget definitions | + +## Automation Protocol (7 protocols) + +Workflows, flows, and integrations. + +| Protocol | Source File | Key Schemas | Purpose | +|:---------|:-----------|:------------|:--------| +| **[Flow](./automation/flow)** | `flow.zod.ts` | Flow, FlowNode | Visual workflow builder | +| **[Workflow](./automation/workflow)** | `workflow.zod.ts` | WorkflowRule | Record-triggered automation | +| **[Approval](./automation/approval)** | `approval.zod.ts` | ApprovalProcess | Multi-step approval flows | +| **[Webhook](./automation/webhook)** | `webhook.zod.ts` | Webhook, WebhookEvent | Outbound webhooks | +| **[ETL](./automation/etl)** | `etl.zod.ts` | ETLPipeline | Data transformation pipelines | +| **[Sync](./automation/sync)** | `sync.zod.ts` | SyncConfig | Bi-directional data sync | +| **[Connector](./automation/connector)** | `connector.zod.ts` | Connector, ConnectorType | External system connectors | + +## System Protocol (14 protocols) + +Core system configuration and runtime infrastructure. + +| Protocol | Source File | Key Schemas | Purpose | +|:---------|:-----------|:------------|:--------| +| **[Manifest](./system/manifest)** | `manifest.zod.ts` | Manifest | Package manifest (objectstack.config.ts) | +| **[Datasource](./system/datasource)** | `datasource.zod.ts` | Datasource, DatasourceType | Database connection configs | +| **[Driver](./system/driver)** | `driver.zod.ts` | Driver, DriverCapabilities | Database driver interface | +| **[Plugin](./system/plugin)** | `plugin.zod.ts` | Plugin, PluginHook | Plugin system interface | +| **[Context](./system/context)** | `context.zod.ts` | KernelContext | Runtime execution context | +| **[Events](./system/events)** | `events.zod.ts` | Event, EventBus | System event bus | +| **[Job](./system/job)** | `job.zod.ts` | Job, JobSchedule | Background job queue | +| **[Audit](./system/audit)** | `audit.zod.ts` | AuditLog, AuditEvent | Audit trail logging | +| **[Logger](./system/logger)** | `logger.zod.ts` | LoggerConfig | Logging configuration | +| **[Translation](./system/translation)** | `translation.zod.ts` | Translation | i18n support | +| **[Feature](./system/feature)** | `feature.zod.ts` | FeatureFlag | Feature flags | +| **[Storage](./system/scoped-storage)** | `scoped-storage.zod.ts` | ScopedStorage | Key-value storage | +| **[Postgres Config](./system/misc)** | `postgres.zod.ts` | PostgresConfig | PostgreSQL driver config | +| **[Mongo Config](./system/misc)** | `mongo.zod.ts` | MongoConfig | MongoDB driver config | + +## AI Protocol (8 protocols) + +AI/ML capabilities - agents, models, RAG, and cost tracking. + +| Protocol | Source File | Key Schemas | Purpose | +|:---------|:-----------|:------------|:--------| +| **[Agent](./ai/agent)** | `agent.zod.ts` | Agent, AITool | AI agent definitions | +| **[Model Registry](./ai/model-registry)** | `model-registry.zod.ts` | ModelRegistry, ModelProvider | LLM model management | +| **[RAG Pipeline](./ai/rag-pipeline)** | `rag-pipeline.zod.ts` | RAGPipelineConfig | Retrieval augmented generation | +| **[NLQ](./ai/nlq)** | `nlq.zod.ts` | NLQRequest, NLQResponse | Natural language to query | +| **[Conversation](./ai/conversation)** | `conversation.zod.ts` | ConversationSession | Conversation management | +| **[Cost](./ai/cost)** | `cost.zod.ts` | CostEntry, BudgetLimit | AI cost tracking and budgets | +| **[Predictive](./ai/predictive)** | `predictive.zod.ts` | PredictiveModel | Predictive ML models | +| **[Orchestration](./ai/orchestration)** | `orchestration.zod.ts` | AIOrchestration | Multi-agent orchestration | + +## API Protocol (6 protocols) + +REST/GraphQL endpoints and real-time subscriptions. + +| Protocol | Source File | Key Schemas | Purpose | +|:---------|:-----------|:------------|:--------| +| **[Contract](./api/contract)** | `contract.zod.ts` | APIContract | API contract definitions | +| **[Endpoint](./api/endpoint)** | `endpoint.zod.ts` | Endpoint, EndpointMethod | REST endpoint configuration | +| **[Router](./api/router)** | `router.zod.ts` | Router, Route | API routing rules | +| **[OData](./api/odata)** | `odata.zod.ts` | ODataQuery | OData protocol support | +| **[Realtime](./api/realtime)** | `realtime.zod.ts` | Subscription, Channel | WebSocket subscriptions | +| **[Discovery](./api/discovery)** | `discovery.zod.ts` | ServiceDiscovery | API discovery and metadata | + +## Auth Protocol (6 protocols) + +Authentication, authorization, and identity management. + +| Protocol | Source File | Key Schemas | Purpose | +|:---------|:-----------|:------------|:--------| +| **[Identity](./auth/identity)** | `identity.zod.ts` | Identity, User | User identity management | +| **[Role](./auth/role)** | `role.zod.ts` | Role, Permission | Role-based access control | +| **[Organization](./auth/organization)** | `organization.zod.ts` | Organization | Multi-organization support | +| **[Policy](./auth/policy)** | `policy.zod.ts` | SecurityPolicy | Security policies | +| **[Config](./auth/config)** | `config.zod.ts` | AuthConfig | OAuth/SAML/SSO configuration | +| **[SCIM](./auth/scim)** | `scim.zod.ts` | SCIMUser, SCIMGroup | SCIM 2.0 provisioning | + +## Permission Protocol (4 protocols) + +Access control and row-level security. + +| Protocol | Source File | Key Schemas | Purpose | +|:---------|:-----------|:------------|:--------| +| **[Permission](./permission/permission)** | `permission.zod.ts` | ObjectPermission | Object-level permissions | +| **[Sharing](./permission/sharing)** | `sharing.zod.ts` | SharingRule | Record sharing rules | +| **[RLS](./permission/rls)** | `rls.zod.ts` | RowLevelSecurity | Row-level security filters | +| **[Territory](./permission/territory)** | `territory.zod.ts` | Territory | Territory-based access | + +## Hub Protocol (5 protocols) + +Marketplace, licensing, and multi-tenancy. + +| Protocol | Source File | Key Schemas | Purpose | +|:---------|:-----------|:------------|:--------| +| **[Marketplace](./hub/marketplace)** | `marketplace.zod.ts` | Package, PackageVersion | Plugin marketplace | +| **[Composer](./hub/composer)** | `composer.zod.ts` | Dependency | Dependency management | +| **[License](./hub/license)** | `license.zod.ts` | License, LicenseType | Feature licensing | +| **[Tenant](./hub/tenant)** | `tenant.zod.ts` | Tenant | Multi-tenancy isolation | +| **[Space](./hub/space)** | `space.zod.ts` | Space, Workspace | Workspace management | + +## Common Patterns + +### Naming Conventions + + + + ```typescript + // Property names in schemas: camelCase + { + maxLength: 100, + defaultValue: 'example', + referenceFilters: ['active = true'] + } + ``` + + + ```typescript + // Machine identifiers in data: snake_case + { + name: 'project_task', + object: 'customer', + field: 'first_name' + } + ``` + + + ```typescript + // Export names: PascalCase + Schema suffix + export const FieldSchema = z.object({...}); + export type Field = z.infer; + ``` + + + +### Common Imports + +```typescript +// Data protocols +import { FieldSchema, ObjectSchema, QuerySchema } from '@objectstack/spec/data'; + +// UI protocols +import { ViewSchema, AppSchema, DashboardSchema } from '@objectstack/spec/ui'; + +// System protocols +import { ManifestSchema, DatasourceSchema } from '@objectstack/spec/system'; + +// AI protocols +import { AgentSchema, RAGPipelineConfigSchema } from '@objectstack/spec/ai'; + +// Types +import type { Field, Object, Query, View } from '@objectstack/spec'; +``` + +## Search Tips + +- **By Feature**: "How do I model relationships?" → [Field Protocol](./data/field) → `lookup` or `master_detail` types +- **By Use Case**: "Build a dashboard" → [Dashboard Protocol](./ui/dashboard) +- **By Layer**: Data → [Data Protocol](./data), UI → [UI Protocol](./ui), Runtime → [System Protocol](./system) + +## Next Steps + + +**New to ObjectStack?** Start with the [Introduction](../introduction) to learn core concepts before diving into specific protocols. + + +- [Protocol Reference Index](./index) - Full protocol documentation +- [ObjectQL Guide](../objectql) - Deep dive into data modeling +- [ObjectUI Guide](../objectui) - UI development guide +- [Contributing Guide](https://github.com/objectstack-ai/spec/blob/main/CONTRIBUTING.md) - How to contribute to protocols diff --git a/content/docs/references/shared/identifiers.mdx b/content/docs/references/shared/identifiers.mdx new file mode 100644 index 000000000..766dcdbcd --- /dev/null +++ b/content/docs/references/shared/identifiers.mdx @@ -0,0 +1,39 @@ +--- +title: Identifiers +description: Identifiers protocol schemas +--- + +# Identifiers + + +**Source:** `packages/spec/src/shared/identifiers.zod.ts` + + +## TypeScript Usage + +```typescript +import { EventNameSchema, SnakeCaseIdentifierSchema, SystemIdentifierSchema } from '@objectstack/spec/shared'; +import type { EventName, SnakeCaseIdentifier, SystemIdentifier } from '@objectstack/spec/shared'; + +// Validate data +const result = EventNameSchema.parse(data); +``` + +--- + +## EventName + +Event name (lowercase with dot notation for namespacing) + +--- + +## SnakeCaseIdentifier + +Snake case identifier (lowercase with underscores only) + +--- + +## SystemIdentifier + +System identifier (lowercase with underscores or dots) + diff --git a/content/docs/references/shared/identifiers/EventName.mdx b/content/docs/references/shared/identifiers/EventName.mdx deleted file mode 100644 index 0f20dc682..000000000 --- a/content/docs/references/shared/identifiers/EventName.mdx +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: EventName -description: Event name (lowercase with dot notation for namespacing) ---- - -Event name (lowercase with dot notation for namespacing) - diff --git a/content/docs/references/shared/identifiers/SnakeCaseIdentifier.mdx b/content/docs/references/shared/identifiers/SnakeCaseIdentifier.mdx deleted file mode 100644 index 1b964ecf9..000000000 --- a/content/docs/references/shared/identifiers/SnakeCaseIdentifier.mdx +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: SnakeCaseIdentifier -description: Snake case identifier (lowercase with underscores only) ---- - -Snake case identifier (lowercase with underscores only) - diff --git a/content/docs/references/shared/identifiers/SystemIdentifier.mdx b/content/docs/references/shared/identifiers/SystemIdentifier.mdx deleted file mode 100644 index dc0ea350a..000000000 --- a/content/docs/references/shared/identifiers/SystemIdentifier.mdx +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: SystemIdentifier -description: System identifier (lowercase with underscores or dots) ---- - -System identifier (lowercase with underscores or dots) - diff --git a/content/docs/references/shared/identifiers/meta.json b/content/docs/references/shared/identifiers/meta.json deleted file mode 100644 index 4d42ed94c..000000000 --- a/content/docs/references/shared/identifiers/meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "title": "Identifiers" -} \ No newline at end of file diff --git a/content/docs/references/shared/index.mdx b/content/docs/references/shared/index.mdx new file mode 100644 index 000000000..8824ca8b8 --- /dev/null +++ b/content/docs/references/shared/index.mdx @@ -0,0 +1,13 @@ +--- +title: Shared Protocol Overview +description: Complete reference for all shared protocol schemas +--- + +# Shared Protocol + +This section contains all protocol schemas for the shared layer of ObjectStack. + + + + + diff --git a/content/docs/references/system/MongoConfig.mdx b/content/docs/references/system/MongoConfig.mdx deleted file mode 100644 index 5698e7c21..000000000 --- a/content/docs/references/system/MongoConfig.mdx +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: MongoConfig -description: MongoConfig Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **url** | `string` | optional | Connection URI | -| **database** | `string` | ✅ | Database Name | -| **host** | `string` | optional | Host address | -| **port** | `number` | optional | Port number | -| **username** | `string` | optional | Auth User | -| **password** | `string` | optional | Auth Password | -| **authSource** | `string` | optional | Authentication Database | -| **ssl** | `boolean` | optional | Enable SSL | -| **replicaSet** | `string` | optional | Replica Set Name | -| **readPreference** | `Enum<'primary' \| 'primaryPreferred' \| 'secondary' \| 'secondaryPreferred' \| 'nearest'>` | optional | Read Preference | -| **maxPoolSize** | `number` | optional | Max Connection Pool Size | -| **minPoolSize** | `number` | optional | Min Connection Pool Size | -| **connectTimeoutMS** | `number` | optional | Connection Timeout (ms) | -| **socketTimeoutMS** | `number` | optional | Socket Timeout (ms) | diff --git a/content/docs/references/system/PostgresConfig.mdx b/content/docs/references/system/PostgresConfig.mdx deleted file mode 100644 index 907050c71..000000000 --- a/content/docs/references/system/PostgresConfig.mdx +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: PostgresConfig -description: PostgresConfig Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **url** | `string` | optional | Connection URI | -| **database** | `string` | ✅ | Database Name | -| **host** | `string` | optional | Host address | -| **port** | `number` | optional | Port number | -| **username** | `string` | optional | Auth User | -| **password** | `string` | optional | Auth Password | -| **schema** | `string` | optional | Default Schema | -| **ssl** | `boolean \| object` | optional | Enable SSL | -| **applicationName** | `string` | optional | Application Name | -| **max** | `number` | optional | Max Pool Size | -| **min** | `number` | optional | Min Pool Size | -| **idleTimeoutMillis** | `number` | optional | Idle Timeout (ms) | -| **connectionTimeoutMillis** | `number` | optional | Connection Timeout (ms) | -| **statementTimeout** | `number` | optional | Statement Timeout (ms) | diff --git a/content/docs/references/system/audit.mdx b/content/docs/references/system/audit.mdx new file mode 100644 index 000000000..fc5a5fb02 --- /dev/null +++ b/content/docs/references/system/audit.mdx @@ -0,0 +1,238 @@ +--- +title: Audit +description: Audit protocol schemas +--- + +# Audit + + +**Source:** `packages/spec/src/system/audit.zod.ts` + + +## TypeScript Usage + +```typescript +import { AuditConfigSchema, AuditEventSchema, AuditEventActorSchema, AuditEventChangeSchema, AuditEventFilterSchema, AuditEventSeveritySchema, AuditEventTargetSchema, AuditEventTypeSchema, AuditRetentionPolicySchema, AuditStorageConfigSchema, SuspiciousActivityRuleSchema } from '@objectstack/spec/system'; +import type { AuditConfig, AuditEvent, AuditEventActor, AuditEventChange, AuditEventFilter, AuditEventSeverity, AuditEventTarget, AuditEventType, AuditRetentionPolicy, AuditStorageConfig, SuspiciousActivityRule } from '@objectstack/spec/system'; + +// Validate data +const result = AuditConfigSchema.parse(data); +``` + +--- + +## AuditConfig + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Configuration name (snake_case, max 64 chars) | +| **label** | `string` | ✅ | Display label | +| **enabled** | `boolean` | optional | Enable audit logging | +| **eventTypes** | `Enum<'data.create' \| 'data.read' \| 'data.update' \| 'data.delete' \| 'data.export' \| 'data.import' \| 'data.bulk_update' \| 'data.bulk_delete' \| 'auth.login' \| 'auth.login_failed' \| 'auth.logout' \| 'auth.session_created' \| 'auth.session_expired' \| 'auth.password_reset' \| 'auth.password_changed' \| 'auth.email_verified' \| 'auth.mfa_enabled' \| 'auth.mfa_disabled' \| 'auth.account_locked' \| 'auth.account_unlocked' \| 'authz.permission_granted' \| 'authz.permission_revoked' \| 'authz.role_assigned' \| 'authz.role_removed' \| 'authz.role_created' \| 'authz.role_updated' \| 'authz.role_deleted' \| 'authz.policy_created' \| 'authz.policy_updated' \| 'authz.policy_deleted' \| 'system.config_changed' \| 'system.plugin_installed' \| 'system.plugin_uninstalled' \| 'system.backup_created' \| 'system.backup_restored' \| 'system.integration_added' \| 'system.integration_removed' \| 'security.access_denied' \| 'security.suspicious_activity' \| 'security.data_breach' \| 'security.api_key_created' \| 'security.api_key_revoked'>[]` | optional | Event types to audit | +| **excludeEventTypes** | `Enum<'data.create' \| 'data.read' \| 'data.update' \| 'data.delete' \| 'data.export' \| 'data.import' \| 'data.bulk_update' \| 'data.bulk_delete' \| 'auth.login' \| 'auth.login_failed' \| 'auth.logout' \| 'auth.session_created' \| 'auth.session_expired' \| 'auth.password_reset' \| 'auth.password_changed' \| 'auth.email_verified' \| 'auth.mfa_enabled' \| 'auth.mfa_disabled' \| 'auth.account_locked' \| 'auth.account_unlocked' \| 'authz.permission_granted' \| 'authz.permission_revoked' \| 'authz.role_assigned' \| 'authz.role_removed' \| 'authz.role_created' \| 'authz.role_updated' \| 'authz.role_deleted' \| 'authz.policy_created' \| 'authz.policy_updated' \| 'authz.policy_deleted' \| 'system.config_changed' \| 'system.plugin_installed' \| 'system.plugin_uninstalled' \| 'system.backup_created' \| 'system.backup_restored' \| 'system.integration_added' \| 'system.integration_removed' \| 'security.access_denied' \| 'security.suspicious_activity' \| 'security.data_breach' \| 'security.api_key_created' \| 'security.api_key_revoked'>[]` | optional | Event types to exclude | +| **minimumSeverity** | `Enum<'debug' \| 'info' \| 'notice' \| 'warning' \| 'error' \| 'critical' \| 'alert' \| 'emergency'>` | optional | Minimum severity level | +| **storage** | `object` | ✅ | Storage configuration | +| **retentionPolicy** | `object` | optional | Retention policy | +| **suspiciousActivityRules** | `object[]` | optional | Suspicious activity rules | +| **includeSensitiveData** | `boolean` | optional | Include sensitive data | +| **redactFields** | `string[]` | optional | Fields to redact | +| **logReads** | `boolean` | optional | Log read operations | +| **readSamplingRate** | `number` | optional | Read sampling rate | +| **logSystemEvents** | `boolean` | optional | Log system events | +| **customHandlers** | `object[]` | optional | Custom event handler references | +| **compliance** | `object` | optional | Compliance configuration | + +--- + +## AuditEvent + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | ✅ | Audit event ID | +| **eventType** | `Enum<'data.create' \| 'data.read' \| 'data.update' \| 'data.delete' \| 'data.export' \| 'data.import' \| 'data.bulk_update' \| 'data.bulk_delete' \| 'auth.login' \| 'auth.login_failed' \| 'auth.logout' \| 'auth.session_created' \| 'auth.session_expired' \| 'auth.password_reset' \| 'auth.password_changed' \| 'auth.email_verified' \| 'auth.mfa_enabled' \| 'auth.mfa_disabled' \| 'auth.account_locked' \| 'auth.account_unlocked' \| 'authz.permission_granted' \| 'authz.permission_revoked' \| 'authz.role_assigned' \| 'authz.role_removed' \| 'authz.role_created' \| 'authz.role_updated' \| 'authz.role_deleted' \| 'authz.policy_created' \| 'authz.policy_updated' \| 'authz.policy_deleted' \| 'system.config_changed' \| 'system.plugin_installed' \| 'system.plugin_uninstalled' \| 'system.backup_created' \| 'system.backup_restored' \| 'system.integration_added' \| 'system.integration_removed' \| 'security.access_denied' \| 'security.suspicious_activity' \| 'security.data_breach' \| 'security.api_key_created' \| 'security.api_key_revoked'>` | ✅ | Event type | +| **severity** | `Enum<'debug' \| 'info' \| 'notice' \| 'warning' \| 'error' \| 'critical' \| 'alert' \| 'emergency'>` | optional | Event severity | +| **timestamp** | `string` | ✅ | Event timestamp | +| **actor** | `object` | ✅ | Event actor | +| **target** | `object` | optional | Event target | +| **description** | `string` | ✅ | Event description | +| **changes** | `object[]` | optional | List of changes | +| **result** | `Enum<'success' \| 'failure' \| 'partial'>` | optional | Action result | +| **errorMessage** | `string` | optional | Error message | +| **tenantId** | `string` | optional | Tenant identifier | +| **requestId** | `string` | optional | Request ID for tracing | +| **metadata** | `Record` | optional | Additional metadata | +| **location** | `object` | optional | Geographic location | + +--- + +## AuditEventActor + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **type** | `Enum<'user' \| 'system' \| 'service' \| 'api_client' \| 'integration'>` | ✅ | Actor type | +| **id** | `string` | ✅ | Actor identifier | +| **name** | `string` | optional | Actor display name | +| **email** | `string` | optional | Actor email address | +| **ipAddress** | `string` | optional | Actor IP address | +| **userAgent** | `string` | optional | User agent string | + +--- + +## AuditEventChange + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **field** | `string` | ✅ | Changed field name | +| **oldValue** | `any` | optional | Previous value | +| **newValue** | `any` | optional | New value | + +--- + +## AuditEventFilter + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **eventTypes** | `Enum<'data.create' \| 'data.read' \| 'data.update' \| 'data.delete' \| 'data.export' \| 'data.import' \| 'data.bulk_update' \| 'data.bulk_delete' \| 'auth.login' \| 'auth.login_failed' \| 'auth.logout' \| 'auth.session_created' \| 'auth.session_expired' \| 'auth.password_reset' \| 'auth.password_changed' \| 'auth.email_verified' \| 'auth.mfa_enabled' \| 'auth.mfa_disabled' \| 'auth.account_locked' \| 'auth.account_unlocked' \| 'authz.permission_granted' \| 'authz.permission_revoked' \| 'authz.role_assigned' \| 'authz.role_removed' \| 'authz.role_created' \| 'authz.role_updated' \| 'authz.role_deleted' \| 'authz.policy_created' \| 'authz.policy_updated' \| 'authz.policy_deleted' \| 'system.config_changed' \| 'system.plugin_installed' \| 'system.plugin_uninstalled' \| 'system.backup_created' \| 'system.backup_restored' \| 'system.integration_added' \| 'system.integration_removed' \| 'security.access_denied' \| 'security.suspicious_activity' \| 'security.data_breach' \| 'security.api_key_created' \| 'security.api_key_revoked'>[]` | optional | Event types to include | +| **severities** | `Enum<'debug' \| 'info' \| 'notice' \| 'warning' \| 'error' \| 'critical' \| 'alert' \| 'emergency'>[]` | optional | Severity levels to include | +| **actorId** | `string` | optional | Actor identifier | +| **tenantId** | `string` | optional | Tenant identifier | +| **timeRange** | `object` | optional | Time range filter | +| **result** | `Enum<'success' \| 'failure' \| 'partial'>` | optional | Result status | +| **searchQuery** | `string` | optional | Search query | +| **customFilters** | `Record` | optional | Custom filters | + +--- + +## AuditEventSeverity + +### Allowed Values + +* `debug` +* `info` +* `notice` +* `warning` +* `error` +* `critical` +* `alert` +* `emergency` + +--- + +## AuditEventTarget + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **type** | `string` | ✅ | Target type | +| **id** | `string` | ✅ | Target identifier | +| **name** | `string` | optional | Target display name | +| **metadata** | `Record` | optional | Target metadata | + +--- + +## AuditEventType + +### Allowed Values + +* `data.create` +* `data.read` +* `data.update` +* `data.delete` +* `data.export` +* `data.import` +* `data.bulk_update` +* `data.bulk_delete` +* `auth.login` +* `auth.login_failed` +* `auth.logout` +* `auth.session_created` +* `auth.session_expired` +* `auth.password_reset` +* `auth.password_changed` +* `auth.email_verified` +* `auth.mfa_enabled` +* `auth.mfa_disabled` +* `auth.account_locked` +* `auth.account_unlocked` +* `authz.permission_granted` +* `authz.permission_revoked` +* `authz.role_assigned` +* `authz.role_removed` +* `authz.role_created` +* `authz.role_updated` +* `authz.role_deleted` +* `authz.policy_created` +* `authz.policy_updated` +* `authz.policy_deleted` +* `system.config_changed` +* `system.plugin_installed` +* `system.plugin_uninstalled` +* `system.backup_created` +* `system.backup_restored` +* `system.integration_added` +* `system.integration_removed` +* `security.access_denied` +* `security.suspicious_activity` +* `security.data_breach` +* `security.api_key_created` +* `security.api_key_revoked` + +--- + +## AuditRetentionPolicy + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **retentionDays** | `integer` | optional | Retention period in days | +| **archiveAfterRetention** | `boolean` | optional | Archive logs after retention period | +| **archiveStorage** | `object` | optional | Archive storage configuration | +| **customRetention** | `Record` | optional | Custom retention by event type | +| **minimumRetentionDays** | `integer` | optional | Minimum retention for compliance | + +--- + +## AuditStorageConfig + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **type** | `Enum<'database' \| 'elasticsearch' \| 'mongodb' \| 'clickhouse' \| 's3' \| 'gcs' \| 'azure_blob' \| 'custom'>` | ✅ | Storage backend type | +| **connectionString** | `string` | optional | Connection string | +| **config** | `Record` | optional | Storage-specific configuration | +| **bufferEnabled** | `boolean` | optional | Enable buffering | +| **bufferSize** | `integer` | optional | Buffer size | +| **flushIntervalSeconds** | `integer` | optional | Flush interval in seconds | +| **compression** | `boolean` | optional | Enable compression | + +--- + +## SuspiciousActivityRule + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | ✅ | Rule identifier | +| **name** | `string` | ✅ | Rule name | +| **description** | `string` | optional | Rule description | +| **enabled** | `boolean` | optional | Rule enabled status | +| **eventTypes** | `Enum<'data.create' \| 'data.read' \| 'data.update' \| 'data.delete' \| 'data.export' \| 'data.import' \| 'data.bulk_update' \| 'data.bulk_delete' \| 'auth.login' \| 'auth.login_failed' \| 'auth.logout' \| 'auth.session_created' \| 'auth.session_expired' \| 'auth.password_reset' \| 'auth.password_changed' \| 'auth.email_verified' \| 'auth.mfa_enabled' \| 'auth.mfa_disabled' \| 'auth.account_locked' \| 'auth.account_unlocked' \| 'authz.permission_granted' \| 'authz.permission_revoked' \| 'authz.role_assigned' \| 'authz.role_removed' \| 'authz.role_created' \| 'authz.role_updated' \| 'authz.role_deleted' \| 'authz.policy_created' \| 'authz.policy_updated' \| 'authz.policy_deleted' \| 'system.config_changed' \| 'system.plugin_installed' \| 'system.plugin_uninstalled' \| 'system.backup_created' \| 'system.backup_restored' \| 'system.integration_added' \| 'system.integration_removed' \| 'security.access_denied' \| 'security.suspicious_activity' \| 'security.data_breach' \| 'security.api_key_created' \| 'security.api_key_revoked'>[]` | ✅ | Event types to monitor | +| **condition** | `object` | ✅ | Detection condition | +| **actions** | `Enum<'alert' \| 'lock_account' \| 'block_ip' \| 'require_mfa' \| 'log_critical' \| 'webhook'>[]` | ✅ | Actions to take | +| **alertSeverity** | `Enum<'debug' \| 'info' \| 'notice' \| 'warning' \| 'error' \| 'critical' \| 'alert' \| 'emergency'>` | optional | Alert severity | +| **notifications** | `object` | optional | Notification configuration | + diff --git a/content/docs/references/system/audit/AuditConfig.mdx b/content/docs/references/system/audit/AuditConfig.mdx deleted file mode 100644 index feebef7d9..000000000 --- a/content/docs/references/system/audit/AuditConfig.mdx +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: AuditConfig -description: AuditConfig Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Configuration name (snake_case, max 64 chars) | -| **label** | `string` | ✅ | Display label | -| **enabled** | `boolean` | optional | Enable audit logging | -| **eventTypes** | `Enum<'data.create' \| 'data.read' \| 'data.update' \| 'data.delete' \| 'data.export' \| 'data.import' \| 'data.bulk_update' \| 'data.bulk_delete' \| 'auth.login' \| 'auth.login_failed' \| 'auth.logout' \| 'auth.session_created' \| 'auth.session_expired' \| 'auth.password_reset' \| 'auth.password_changed' \| 'auth.email_verified' \| 'auth.mfa_enabled' \| 'auth.mfa_disabled' \| 'auth.account_locked' \| 'auth.account_unlocked' \| 'authz.permission_granted' \| 'authz.permission_revoked' \| 'authz.role_assigned' \| 'authz.role_removed' \| 'authz.role_created' \| 'authz.role_updated' \| 'authz.role_deleted' \| 'authz.policy_created' \| 'authz.policy_updated' \| 'authz.policy_deleted' \| 'system.config_changed' \| 'system.plugin_installed' \| 'system.plugin_uninstalled' \| 'system.backup_created' \| 'system.backup_restored' \| 'system.integration_added' \| 'system.integration_removed' \| 'security.access_denied' \| 'security.suspicious_activity' \| 'security.data_breach' \| 'security.api_key_created' \| 'security.api_key_revoked'>[]` | optional | Event types to audit | -| **excludeEventTypes** | `Enum<'data.create' \| 'data.read' \| 'data.update' \| 'data.delete' \| 'data.export' \| 'data.import' \| 'data.bulk_update' \| 'data.bulk_delete' \| 'auth.login' \| 'auth.login_failed' \| 'auth.logout' \| 'auth.session_created' \| 'auth.session_expired' \| 'auth.password_reset' \| 'auth.password_changed' \| 'auth.email_verified' \| 'auth.mfa_enabled' \| 'auth.mfa_disabled' \| 'auth.account_locked' \| 'auth.account_unlocked' \| 'authz.permission_granted' \| 'authz.permission_revoked' \| 'authz.role_assigned' \| 'authz.role_removed' \| 'authz.role_created' \| 'authz.role_updated' \| 'authz.role_deleted' \| 'authz.policy_created' \| 'authz.policy_updated' \| 'authz.policy_deleted' \| 'system.config_changed' \| 'system.plugin_installed' \| 'system.plugin_uninstalled' \| 'system.backup_created' \| 'system.backup_restored' \| 'system.integration_added' \| 'system.integration_removed' \| 'security.access_denied' \| 'security.suspicious_activity' \| 'security.data_breach' \| 'security.api_key_created' \| 'security.api_key_revoked'>[]` | optional | Event types to exclude | -| **minimumSeverity** | `Enum<'debug' \| 'info' \| 'notice' \| 'warning' \| 'error' \| 'critical' \| 'alert' \| 'emergency'>` | optional | Minimum severity level | -| **storage** | `object` | ✅ | Storage configuration | -| **retentionPolicy** | `object` | optional | Retention policy | -| **suspiciousActivityRules** | `object[]` | optional | Suspicious activity rules | -| **includeSensitiveData** | `boolean` | optional | Include sensitive data | -| **redactFields** | `string[]` | optional | Fields to redact | -| **logReads** | `boolean` | optional | Log read operations | -| **readSamplingRate** | `number` | optional | Read sampling rate | -| **logSystemEvents** | `boolean` | optional | Log system events | -| **customHandlers** | `object[]` | optional | Custom event handler references | -| **compliance** | `object` | optional | Compliance configuration | diff --git a/content/docs/references/system/audit/AuditEvent.mdx b/content/docs/references/system/audit/AuditEvent.mdx deleted file mode 100644 index a1bc3ed39..000000000 --- a/content/docs/references/system/audit/AuditEvent.mdx +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: AuditEvent -description: AuditEvent Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Audit event ID | -| **eventType** | `Enum<'data.create' \| 'data.read' \| 'data.update' \| 'data.delete' \| 'data.export' \| 'data.import' \| 'data.bulk_update' \| 'data.bulk_delete' \| 'auth.login' \| 'auth.login_failed' \| 'auth.logout' \| 'auth.session_created' \| 'auth.session_expired' \| 'auth.password_reset' \| 'auth.password_changed' \| 'auth.email_verified' \| 'auth.mfa_enabled' \| 'auth.mfa_disabled' \| 'auth.account_locked' \| 'auth.account_unlocked' \| 'authz.permission_granted' \| 'authz.permission_revoked' \| 'authz.role_assigned' \| 'authz.role_removed' \| 'authz.role_created' \| 'authz.role_updated' \| 'authz.role_deleted' \| 'authz.policy_created' \| 'authz.policy_updated' \| 'authz.policy_deleted' \| 'system.config_changed' \| 'system.plugin_installed' \| 'system.plugin_uninstalled' \| 'system.backup_created' \| 'system.backup_restored' \| 'system.integration_added' \| 'system.integration_removed' \| 'security.access_denied' \| 'security.suspicious_activity' \| 'security.data_breach' \| 'security.api_key_created' \| 'security.api_key_revoked'>` | ✅ | Event type | -| **severity** | `Enum<'debug' \| 'info' \| 'notice' \| 'warning' \| 'error' \| 'critical' \| 'alert' \| 'emergency'>` | optional | Event severity | -| **timestamp** | `string` | ✅ | Event timestamp | -| **actor** | `object` | ✅ | Event actor | -| **target** | `object` | optional | Event target | -| **description** | `string` | ✅ | Event description | -| **changes** | `object[]` | optional | List of changes | -| **result** | `Enum<'success' \| 'failure' \| 'partial'>` | optional | Action result | -| **errorMessage** | `string` | optional | Error message | -| **tenantId** | `string` | optional | Tenant identifier | -| **requestId** | `string` | optional | Request ID for tracing | -| **metadata** | `Record` | optional | Additional metadata | -| **location** | `object` | optional | Geographic location | diff --git a/content/docs/references/system/audit/AuditEventActor.mdx b/content/docs/references/system/audit/AuditEventActor.mdx deleted file mode 100644 index f59a630a4..000000000 --- a/content/docs/references/system/audit/AuditEventActor.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: AuditEventActor -description: AuditEventActor Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `Enum<'user' \| 'system' \| 'service' \| 'api_client' \| 'integration'>` | ✅ | Actor type | -| **id** | `string` | ✅ | Actor identifier | -| **name** | `string` | optional | Actor display name | -| **email** | `string` | optional | Actor email address | -| **ipAddress** | `string` | optional | Actor IP address | -| **userAgent** | `string` | optional | User agent string | diff --git a/content/docs/references/system/audit/AuditEventChange.mdx b/content/docs/references/system/audit/AuditEventChange.mdx deleted file mode 100644 index 9ab45b293..000000000 --- a/content/docs/references/system/audit/AuditEventChange.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: AuditEventChange -description: AuditEventChange Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **field** | `string` | ✅ | Changed field name | -| **oldValue** | `any` | optional | Previous value | -| **newValue** | `any` | optional | New value | diff --git a/content/docs/references/system/audit/AuditEventFilter.mdx b/content/docs/references/system/audit/AuditEventFilter.mdx deleted file mode 100644 index 013cf44e0..000000000 --- a/content/docs/references/system/audit/AuditEventFilter.mdx +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: AuditEventFilter -description: AuditEventFilter Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **eventTypes** | `Enum<'data.create' \| 'data.read' \| 'data.update' \| 'data.delete' \| 'data.export' \| 'data.import' \| 'data.bulk_update' \| 'data.bulk_delete' \| 'auth.login' \| 'auth.login_failed' \| 'auth.logout' \| 'auth.session_created' \| 'auth.session_expired' \| 'auth.password_reset' \| 'auth.password_changed' \| 'auth.email_verified' \| 'auth.mfa_enabled' \| 'auth.mfa_disabled' \| 'auth.account_locked' \| 'auth.account_unlocked' \| 'authz.permission_granted' \| 'authz.permission_revoked' \| 'authz.role_assigned' \| 'authz.role_removed' \| 'authz.role_created' \| 'authz.role_updated' \| 'authz.role_deleted' \| 'authz.policy_created' \| 'authz.policy_updated' \| 'authz.policy_deleted' \| 'system.config_changed' \| 'system.plugin_installed' \| 'system.plugin_uninstalled' \| 'system.backup_created' \| 'system.backup_restored' \| 'system.integration_added' \| 'system.integration_removed' \| 'security.access_denied' \| 'security.suspicious_activity' \| 'security.data_breach' \| 'security.api_key_created' \| 'security.api_key_revoked'>[]` | optional | Event types to include | -| **severities** | `Enum<'debug' \| 'info' \| 'notice' \| 'warning' \| 'error' \| 'critical' \| 'alert' \| 'emergency'>[]` | optional | Severity levels to include | -| **actorId** | `string` | optional | Actor identifier | -| **tenantId** | `string` | optional | Tenant identifier | -| **timeRange** | `object` | optional | Time range filter | -| **result** | `Enum<'success' \| 'failure' \| 'partial'>` | optional | Result status | -| **searchQuery** | `string` | optional | Search query | -| **customFilters** | `Record` | optional | Custom filters | diff --git a/content/docs/references/system/audit/AuditEventSeverity.mdx b/content/docs/references/system/audit/AuditEventSeverity.mdx deleted file mode 100644 index 41d142d29..000000000 --- a/content/docs/references/system/audit/AuditEventSeverity.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: AuditEventSeverity -description: AuditEventSeverity Schema Reference ---- - -## Allowed Values - -* `debug` -* `info` -* `notice` -* `warning` -* `error` -* `critical` -* `alert` -* `emergency` \ No newline at end of file diff --git a/content/docs/references/system/audit/AuditEventTarget.mdx b/content/docs/references/system/audit/AuditEventTarget.mdx deleted file mode 100644 index 040747df5..000000000 --- a/content/docs/references/system/audit/AuditEventTarget.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: AuditEventTarget -description: AuditEventTarget Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | Target type | -| **id** | `string` | ✅ | Target identifier | -| **name** | `string` | optional | Target display name | -| **metadata** | `Record` | optional | Target metadata | diff --git a/content/docs/references/system/audit/AuditEventType.mdx b/content/docs/references/system/audit/AuditEventType.mdx deleted file mode 100644 index 4f6a42351..000000000 --- a/content/docs/references/system/audit/AuditEventType.mdx +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: AuditEventType -description: AuditEventType Schema Reference ---- - -## Allowed Values - -* `data.create` -* `data.read` -* `data.update` -* `data.delete` -* `data.export` -* `data.import` -* `data.bulk_update` -* `data.bulk_delete` -* `auth.login` -* `auth.login_failed` -* `auth.logout` -* `auth.session_created` -* `auth.session_expired` -* `auth.password_reset` -* `auth.password_changed` -* `auth.email_verified` -* `auth.mfa_enabled` -* `auth.mfa_disabled` -* `auth.account_locked` -* `auth.account_unlocked` -* `authz.permission_granted` -* `authz.permission_revoked` -* `authz.role_assigned` -* `authz.role_removed` -* `authz.role_created` -* `authz.role_updated` -* `authz.role_deleted` -* `authz.policy_created` -* `authz.policy_updated` -* `authz.policy_deleted` -* `system.config_changed` -* `system.plugin_installed` -* `system.plugin_uninstalled` -* `system.backup_created` -* `system.backup_restored` -* `system.integration_added` -* `system.integration_removed` -* `security.access_denied` -* `security.suspicious_activity` -* `security.data_breach` -* `security.api_key_created` -* `security.api_key_revoked` \ No newline at end of file diff --git a/content/docs/references/system/audit/AuditRetentionPolicy.mdx b/content/docs/references/system/audit/AuditRetentionPolicy.mdx deleted file mode 100644 index fdb5c24d7..000000000 --- a/content/docs/references/system/audit/AuditRetentionPolicy.mdx +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: AuditRetentionPolicy -description: AuditRetentionPolicy Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **retentionDays** | `integer` | optional | Retention period in days | -| **archiveAfterRetention** | `boolean` | optional | Archive logs after retention period | -| **archiveStorage** | `object` | optional | Archive storage configuration | -| **customRetention** | `Record` | optional | Custom retention by event type | -| **minimumRetentionDays** | `integer` | optional | Minimum retention for compliance | diff --git a/content/docs/references/system/audit/AuditStorageConfig.mdx b/content/docs/references/system/audit/AuditStorageConfig.mdx deleted file mode 100644 index 2938b8fb3..000000000 --- a/content/docs/references/system/audit/AuditStorageConfig.mdx +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: AuditStorageConfig -description: AuditStorageConfig Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `Enum<'database' \| 'elasticsearch' \| 'mongodb' \| 'clickhouse' \| 's3' \| 'gcs' \| 'azure_blob' \| 'custom'>` | ✅ | Storage backend type | -| **connectionString** | `string` | optional | Connection string | -| **config** | `Record` | optional | Storage-specific configuration | -| **bufferEnabled** | `boolean` | optional | Enable buffering | -| **bufferSize** | `integer` | optional | Buffer size | -| **flushIntervalSeconds** | `integer` | optional | Flush interval in seconds | -| **compression** | `boolean` | optional | Enable compression | diff --git a/content/docs/references/system/audit/SuspiciousActivityRule.mdx b/content/docs/references/system/audit/SuspiciousActivityRule.mdx deleted file mode 100644 index 7bd718083..000000000 --- a/content/docs/references/system/audit/SuspiciousActivityRule.mdx +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: SuspiciousActivityRule -description: SuspiciousActivityRule Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Rule identifier | -| **name** | `string` | ✅ | Rule name | -| **description** | `string` | optional | Rule description | -| **enabled** | `boolean` | optional | Rule enabled status | -| **eventTypes** | `Enum<'data.create' \| 'data.read' \| 'data.update' \| 'data.delete' \| 'data.export' \| 'data.import' \| 'data.bulk_update' \| 'data.bulk_delete' \| 'auth.login' \| 'auth.login_failed' \| 'auth.logout' \| 'auth.session_created' \| 'auth.session_expired' \| 'auth.password_reset' \| 'auth.password_changed' \| 'auth.email_verified' \| 'auth.mfa_enabled' \| 'auth.mfa_disabled' \| 'auth.account_locked' \| 'auth.account_unlocked' \| 'authz.permission_granted' \| 'authz.permission_revoked' \| 'authz.role_assigned' \| 'authz.role_removed' \| 'authz.role_created' \| 'authz.role_updated' \| 'authz.role_deleted' \| 'authz.policy_created' \| 'authz.policy_updated' \| 'authz.policy_deleted' \| 'system.config_changed' \| 'system.plugin_installed' \| 'system.plugin_uninstalled' \| 'system.backup_created' \| 'system.backup_restored' \| 'system.integration_added' \| 'system.integration_removed' \| 'security.access_denied' \| 'security.suspicious_activity' \| 'security.data_breach' \| 'security.api_key_created' \| 'security.api_key_revoked'>[]` | ✅ | Event types to monitor | -| **condition** | `object` | ✅ | Detection condition | -| **actions** | `Enum<'alert' \| 'lock_account' \| 'block_ip' \| 'require_mfa' \| 'log_critical' \| 'webhook'>[]` | ✅ | Actions to take | -| **alertSeverity** | `Enum<'debug' \| 'info' \| 'notice' \| 'warning' \| 'error' \| 'critical' \| 'alert' \| 'emergency'>` | optional | Alert severity | -| **notifications** | `object` | optional | Notification configuration | diff --git a/content/docs/references/system/audit/meta.json b/content/docs/references/system/audit/meta.json deleted file mode 100644 index 22cff814c..000000000 --- a/content/docs/references/system/audit/meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "title": "Audit" -} \ No newline at end of file diff --git a/content/docs/references/system/context/KernelContext.mdx b/content/docs/references/system/context.mdx similarity index 53% rename from content/docs/references/system/context/KernelContext.mdx rename to content/docs/references/system/context.mdx index 4634402d9..0911bc9ef 100644 --- a/content/docs/references/system/context/KernelContext.mdx +++ b/content/docs/references/system/context.mdx @@ -1,9 +1,29 @@ --- -title: KernelContext -description: KernelContext Schema Reference +title: Context +description: Context protocol schemas --- -## Properties +# Context + + +**Source:** `packages/spec/src/system/context.zod.ts` + + +## TypeScript Usage + +```typescript +import { KernelContextSchema, RuntimeModeSchema } from '@objectstack/spec/system'; +import type { KernelContext, RuntimeMode } from '@objectstack/spec/system'; + +// Validate data +const result = KernelContextSchema.parse(data); +``` + +--- + +## KernelContext + +### Properties | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | @@ -15,3 +35,17 @@ description: KernelContext Schema Reference | **workspaceRoot** | `string` | optional | Workspace root if different from cwd | | **startTime** | `integer` | ✅ | Boot timestamp (ms) | | **features** | `Record` | optional | Global feature toggles | + +--- + +## RuntimeMode + +Kernel operating mode + +### Allowed Values + +* `development` +* `production` +* `test` +* `provisioning` + diff --git a/content/docs/references/system/context/RuntimeMode.mdx b/content/docs/references/system/context/RuntimeMode.mdx deleted file mode 100644 index 3bb6e9869..000000000 --- a/content/docs/references/system/context/RuntimeMode.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: RuntimeMode -description: Kernel operating mode ---- - -Kernel operating mode - -## Allowed Values - -* `development` -* `production` -* `test` -* `provisioning` \ No newline at end of file diff --git a/content/docs/references/system/context/meta.json b/content/docs/references/system/context/meta.json deleted file mode 100644 index 807685cb1..000000000 --- a/content/docs/references/system/context/meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "title": "Context" -} \ No newline at end of file diff --git a/content/docs/references/system/datasource.mdx b/content/docs/references/system/datasource.mdx new file mode 100644 index 000000000..a908b2864 --- /dev/null +++ b/content/docs/references/system/datasource.mdx @@ -0,0 +1,80 @@ +--- +title: Datasource +description: Datasource protocol schemas +--- + +# Datasource + + +**Source:** `packages/spec/src/system/datasource.zod.ts` + + +## TypeScript Usage + +```typescript +import { DatasourceSchema, DatasourceCapabilitiesSchema, DriverDefinitionSchema, DriverTypeSchema } from '@objectstack/spec/system'; +import type { Datasource, DatasourceCapabilities, DriverDefinition, DriverType } from '@objectstack/spec/system'; + +// Validate data +const result = DatasourceSchema.parse(data); +``` + +--- + +## Datasource + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Unique datasource identifier | +| **label** | `string` | optional | Display label | +| **driver** | `string` | ✅ | Underlying driver type | +| **config** | `Record` | ✅ | Driver specific configuration | +| **pool** | `object` | optional | Connection pool settings | +| **readReplicas** | `Record[]` | optional | Read-only replica configurations | +| **capabilities** | `object` | optional | Capability overrides | +| **description** | `string` | optional | Internal description | +| **active** | `boolean` | optional | Is datasource enabled | + +--- + +## DatasourceCapabilities + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **transactions** | `boolean` | optional | | +| **queryFilters** | `boolean` | optional | | +| **queryAggregations** | `boolean` | optional | | +| **querySorting** | `boolean` | optional | | +| **queryPagination** | `boolean` | optional | | +| **queryWindowFunctions** | `boolean` | optional | | +| **querySubqueries** | `boolean` | optional | | +| **joins** | `boolean` | optional | | +| **fullTextSearch** | `boolean` | optional | | +| **readOnly** | `boolean` | optional | | +| **dynamicSchema** | `boolean` | optional | | + +--- + +## DriverDefinition + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | ✅ | Unique driver identifier (e.g. "postgres") | +| **label** | `string` | ✅ | Display label (e.g. "PostgreSQL") | +| **description** | `string` | optional | | +| **icon** | `string` | optional | | +| **configSchema** | `Record` | ✅ | JSON Schema for connection configuration | +| **capabilities** | `object` | optional | | + +--- + +## DriverType + +Underlying driver identifier + diff --git a/content/docs/references/system/datasource/Datasource.mdx b/content/docs/references/system/datasource/Datasource.mdx deleted file mode 100644 index 2d406896b..000000000 --- a/content/docs/references/system/datasource/Datasource.mdx +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Datasource -description: Datasource Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Unique datasource identifier | -| **label** | `string` | optional | Display label | -| **driver** | `string` | ✅ | Underlying driver type | -| **config** | `Record` | ✅ | Driver specific configuration | -| **pool** | `object` | optional | Connection pool settings | -| **readReplicas** | `Record[]` | optional | Read-only replica configurations | -| **capabilities** | `object` | optional | Capability overrides | -| **description** | `string` | optional | Internal description | -| **active** | `boolean` | optional | Is datasource enabled | diff --git a/content/docs/references/system/datasource/DatasourceCapabilities.mdx b/content/docs/references/system/datasource/DatasourceCapabilities.mdx deleted file mode 100644 index c1e512544..000000000 --- a/content/docs/references/system/datasource/DatasourceCapabilities.mdx +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: DatasourceCapabilities -description: DatasourceCapabilities Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **transactions** | `boolean` | optional | | -| **queryFilters** | `boolean` | optional | | -| **queryAggregations** | `boolean` | optional | | -| **querySorting** | `boolean` | optional | | -| **queryPagination** | `boolean` | optional | | -| **queryWindowFunctions** | `boolean` | optional | | -| **querySubqueries** | `boolean` | optional | | -| **joins** | `boolean` | optional | | -| **fullTextSearch** | `boolean` | optional | | -| **readOnly** | `boolean` | optional | | -| **dynamicSchema** | `boolean` | optional | | diff --git a/content/docs/references/system/datasource/DriverDefinition.mdx b/content/docs/references/system/datasource/DriverDefinition.mdx deleted file mode 100644 index b680f3085..000000000 --- a/content/docs/references/system/datasource/DriverDefinition.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: DriverDefinition -description: DriverDefinition Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Unique driver identifier (e.g. "postgres") | -| **label** | `string` | ✅ | Display label (e.g. "PostgreSQL") | -| **description** | `string` | optional | | -| **icon** | `string` | optional | | -| **configSchema** | `Record` | ✅ | JSON Schema for connection configuration | -| **capabilities** | `object` | optional | | diff --git a/content/docs/references/system/datasource/DriverType.mdx b/content/docs/references/system/datasource/DriverType.mdx deleted file mode 100644 index e896a3850..000000000 --- a/content/docs/references/system/datasource/DriverType.mdx +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: DriverType -description: Underlying driver identifier ---- - -Underlying driver identifier - diff --git a/content/docs/references/system/datasource/meta.json b/content/docs/references/system/datasource/meta.json deleted file mode 100644 index 6dfcbf686..000000000 --- a/content/docs/references/system/datasource/meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "title": "Datasource" -} \ No newline at end of file diff --git a/content/docs/references/system/driver.mdx b/content/docs/references/system/driver.mdx new file mode 100644 index 000000000..c6cc834e4 --- /dev/null +++ b/content/docs/references/system/driver.mdx @@ -0,0 +1,69 @@ +--- +title: Driver +description: Driver protocol schemas +--- + +# Driver + + +**Source:** `packages/spec/src/system/driver.zod.ts` + + +## TypeScript Usage + +```typescript +import { DriverCapabilitiesSchema, DriverInterfaceSchema, DriverOptionsSchema } from '@objectstack/spec/system'; +import type { DriverCapabilities, DriverInterface, DriverOptions } from '@objectstack/spec/system'; + +// Validate data +const result = DriverCapabilitiesSchema.parse(data); +``` + +--- + +## DriverCapabilities + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **transactions** | `boolean` | ✅ | Supports transactions | +| **queryFilters** | `boolean` | ✅ | Supports WHERE clause filtering | +| **queryAggregations** | `boolean` | ✅ | Supports GROUP BY and aggregation functions | +| **querySorting** | `boolean` | ✅ | Supports ORDER BY sorting | +| **queryPagination** | `boolean` | ✅ | Supports LIMIT/OFFSET pagination | +| **queryWindowFunctions** | `boolean` | ✅ | Supports window functions with OVER clause | +| **querySubqueries** | `boolean` | ✅ | Supports subqueries | +| **joins** | `boolean` | ✅ | Supports SQL joins | +| **fullTextSearch** | `boolean` | ✅ | Supports full-text search | +| **jsonFields** | `boolean` | ✅ | Supports JSON field types | +| **arrayFields** | `boolean` | ✅ | Supports array field types | +| **vectorSearch** | `boolean` | optional | Supports vector embeddings and similarity search | +| **geoSpatial** | `boolean` | optional | Supports geospatial queries | + +--- + +## DriverInterface + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Driver unique name | +| **version** | `string` | ✅ | Driver version | +| **supports** | `object` | ✅ | | + +--- + +## DriverOptions + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **transaction** | `any` | optional | Transaction handle | +| **timeout** | `number` | optional | Timeout in ms | +| **skipCache** | `boolean` | optional | Bypass cache | +| **traceContext** | `Record` | optional | OpenTelemetry context or request ID | +| **tenantId** | `string` | optional | Tenant Isolation identifier | + diff --git a/content/docs/references/system/driver/DriverCapabilities.mdx b/content/docs/references/system/driver/DriverCapabilities.mdx deleted file mode 100644 index f1a95721d..000000000 --- a/content/docs/references/system/driver/DriverCapabilities.mdx +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: DriverCapabilities -description: DriverCapabilities Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **transactions** | `boolean` | ✅ | Supports transactions | -| **queryFilters** | `boolean` | ✅ | Supports WHERE clause filtering | -| **queryAggregations** | `boolean` | ✅ | Supports GROUP BY and aggregation functions | -| **querySorting** | `boolean` | ✅ | Supports ORDER BY sorting | -| **queryPagination** | `boolean` | ✅ | Supports LIMIT/OFFSET pagination | -| **queryWindowFunctions** | `boolean` | ✅ | Supports window functions with OVER clause | -| **querySubqueries** | `boolean` | ✅ | Supports subqueries | -| **joins** | `boolean` | ✅ | Supports SQL joins | -| **fullTextSearch** | `boolean` | ✅ | Supports full-text search | -| **jsonFields** | `boolean` | ✅ | Supports JSON field types | -| **arrayFields** | `boolean` | ✅ | Supports array field types | -| **vectorSearch** | `boolean` | optional | Supports vector embeddings and similarity search | -| **geoSpatial** | `boolean` | optional | Supports geospatial queries | diff --git a/content/docs/references/system/driver/DriverInterface.mdx b/content/docs/references/system/driver/DriverInterface.mdx deleted file mode 100644 index b31b9a93c..000000000 --- a/content/docs/references/system/driver/DriverInterface.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: DriverInterface -description: DriverInterface Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Driver unique name | -| **version** | `string` | ✅ | Driver version | -| **supports** | `object` | ✅ | | diff --git a/content/docs/references/system/driver/DriverOptions.mdx b/content/docs/references/system/driver/DriverOptions.mdx deleted file mode 100644 index 0f5926019..000000000 --- a/content/docs/references/system/driver/DriverOptions.mdx +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: DriverOptions -description: DriverOptions Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **transaction** | `any` | optional | Transaction handle | -| **timeout** | `number` | optional | Timeout in ms | -| **skipCache** | `boolean` | optional | Bypass cache | -| **traceContext** | `Record` | optional | OpenTelemetry context or request ID | -| **tenantId** | `string` | optional | Tenant Isolation identifier | diff --git a/content/docs/references/system/driver/meta.json b/content/docs/references/system/driver/meta.json deleted file mode 100644 index fa70124c5..000000000 --- a/content/docs/references/system/driver/meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "title": "Driver" -} \ No newline at end of file diff --git a/content/docs/references/system/events.mdx b/content/docs/references/system/events.mdx new file mode 100644 index 000000000..a977a90a7 --- /dev/null +++ b/content/docs/references/system/events.mdx @@ -0,0 +1,80 @@ +--- +title: Events +description: Events protocol schemas +--- + +# Events + + +**Source:** `packages/spec/src/system/events.zod.ts` + + +## TypeScript Usage + +```typescript +import { EventSchema, EventHandlerSchema, EventMetadataSchema, EventPersistenceSchema, EventRouteSchema } from '@objectstack/spec/system'; +import type { Event, EventHandler, EventMetadata, EventPersistence, EventRoute } from '@objectstack/spec/system'; + +// Validate data +const result = EventSchema.parse(data); +``` + +--- + +## Event + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Event name (lowercase with dots, e.g., user.created, order.paid) | +| **payload** | `any` | optional | Event payload schema | +| **metadata** | `object` | ✅ | Event metadata | + +--- + +## EventHandler + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **eventName** | `string` | ✅ | Name of event to handle (supports wildcards like user.*) | +| **priority** | `integer` | optional | Execution priority (lower numbers execute first) | +| **async** | `boolean` | optional | Execute in background (true) or block (false) | + +--- + +## EventMetadata + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **source** | `string` | ✅ | Event source (e.g., plugin name, system component) | +| **timestamp** | `string` | ✅ | ISO 8601 datetime when event was created | +| **userId** | `string` | optional | User who triggered the event | +| **tenantId** | `string` | optional | Tenant identifier for multi-tenant systems | + +--- + +## EventPersistence + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **enabled** | `boolean` | optional | Enable event persistence | +| **retention** | `integer` | ✅ | Days to retain persisted events | + +--- + +## EventRoute + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **from** | `string` | ✅ | Source event pattern (supports wildcards, e.g., user.* or *.created) | +| **to** | `string[]` | ✅ | Target event names to route to | + diff --git a/content/docs/references/system/events/Event.mdx b/content/docs/references/system/events/Event.mdx deleted file mode 100644 index 711083ea0..000000000 --- a/content/docs/references/system/events/Event.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: Event -description: Event Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Event name (lowercase with dots, e.g., user.created, order.paid) | -| **payload** | `any` | optional | Event payload schema | -| **metadata** | `object` | ✅ | Event metadata | diff --git a/content/docs/references/system/events/EventHandler.mdx b/content/docs/references/system/events/EventHandler.mdx deleted file mode 100644 index 994cd5407..000000000 --- a/content/docs/references/system/events/EventHandler.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: EventHandler -description: EventHandler Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **eventName** | `string` | ✅ | Name of event to handle (supports wildcards like user.*) | -| **priority** | `integer` | optional | Execution priority (lower numbers execute first) | -| **async** | `boolean` | optional | Execute in background (true) or block (false) | diff --git a/content/docs/references/system/events/EventMetadata.mdx b/content/docs/references/system/events/EventMetadata.mdx deleted file mode 100644 index 86e4254d0..000000000 --- a/content/docs/references/system/events/EventMetadata.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: EventMetadata -description: EventMetadata Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **source** | `string` | ✅ | Event source (e.g., plugin name, system component) | -| **timestamp** | `string` | ✅ | ISO 8601 datetime when event was created | -| **userId** | `string` | optional | User who triggered the event | -| **tenantId** | `string` | optional | Tenant identifier for multi-tenant systems | diff --git a/content/docs/references/system/events/EventPersistence.mdx b/content/docs/references/system/events/EventPersistence.mdx deleted file mode 100644 index eac9960cc..000000000 --- a/content/docs/references/system/events/EventPersistence.mdx +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: EventPersistence -description: EventPersistence Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | optional | Enable event persistence | -| **retention** | `integer` | ✅ | Days to retain persisted events | diff --git a/content/docs/references/system/events/EventRoute.mdx b/content/docs/references/system/events/EventRoute.mdx deleted file mode 100644 index 39c417154..000000000 --- a/content/docs/references/system/events/EventRoute.mdx +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: EventRoute -description: EventRoute Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **from** | `string` | ✅ | Source event pattern (supports wildcards, e.g., user.* or *.created) | -| **to** | `string[]` | ✅ | Target event names to route to | diff --git a/content/docs/references/system/events/meta.json b/content/docs/references/system/events/meta.json deleted file mode 100644 index b14d07304..000000000 --- a/content/docs/references/system/events/meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "title": "Events" -} \ No newline at end of file diff --git a/content/docs/references/system/feature/FeatureFlag.mdx b/content/docs/references/system/feature.mdx similarity index 52% rename from content/docs/references/system/feature/FeatureFlag.mdx rename to content/docs/references/system/feature.mdx index e19bdd598..9c6c36b6b 100644 --- a/content/docs/references/system/feature/FeatureFlag.mdx +++ b/content/docs/references/system/feature.mdx @@ -1,9 +1,29 @@ --- -title: FeatureFlag -description: FeatureFlag Schema Reference +title: Feature +description: Feature protocol schemas --- -## Properties +# Feature + + +**Source:** `packages/spec/src/system/feature.zod.ts` + + +## TypeScript Usage + +```typescript +import { FeatureFlagSchema, FeatureStrategySchema } from '@objectstack/spec/system'; +import type { FeatureFlag, FeatureStrategy } from '@objectstack/spec/system'; + +// Validate data +const result = FeatureFlagSchema.parse(data); +``` + +--- + +## FeatureFlag + +### Properties | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | @@ -15,3 +35,16 @@ description: FeatureFlag Schema Reference | **conditions** | `object` | optional | | | **environment** | `Enum<'dev' \| 'staging' \| 'prod' \| 'all'>` | optional | Environment validity | | **expiresAt** | `string` | optional | Feature flag expiration date | + +--- + +## FeatureStrategy + +### Allowed Values + +* `boolean` +* `percentage` +* `user_list` +* `group` +* `custom` + diff --git a/content/docs/references/system/feature/FeatureStrategy.mdx b/content/docs/references/system/feature/FeatureStrategy.mdx deleted file mode 100644 index d69930635..000000000 --- a/content/docs/references/system/feature/FeatureStrategy.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: FeatureStrategy -description: FeatureStrategy Schema Reference ---- - -## Allowed Values - -* `boolean` -* `percentage` -* `user_list` -* `group` -* `custom` \ No newline at end of file diff --git a/content/docs/references/system/feature/meta.json b/content/docs/references/system/feature/meta.json deleted file mode 100644 index 8a1211fca..000000000 --- a/content/docs/references/system/feature/meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "title": "Feature" -} \ No newline at end of file diff --git a/content/docs/references/system/index.mdx b/content/docs/references/system/index.mdx new file mode 100644 index 000000000..fa6bcc251 --- /dev/null +++ b/content/docs/references/system/index.mdx @@ -0,0 +1,24 @@ +--- +title: System Protocol Overview +description: Complete reference for all system protocol schemas +--- + +# System Protocol + +This section contains all protocol schemas for the system layer of ObjectStack. + + + + + + + + + + + + + + + + diff --git a/content/docs/references/system/job.mdx b/content/docs/references/system/job.mdx new file mode 100644 index 000000000..7eb0d5740 --- /dev/null +++ b/content/docs/references/system/job.mdx @@ -0,0 +1,112 @@ +--- +title: Job +description: Job protocol schemas +--- + +# Job + + +**Source:** `packages/spec/src/system/job.zod.ts` + + +## TypeScript Usage + +```typescript +import { CronScheduleSchema, IntervalScheduleSchema, JobSchema, JobExecutionSchema, JobExecutionStatusSchema, OnceScheduleSchema, RetryPolicySchema, ScheduleSchema } from '@objectstack/spec/system'; +import type { CronSchedule, IntervalSchedule, Job, JobExecution, JobExecutionStatus, OnceSchedule, RetryPolicy, Schedule } from '@objectstack/spec/system'; + +// Validate data +const result = CronScheduleSchema.parse(data); +``` + +--- + +## CronSchedule + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **type** | `string` | ✅ | | +| **expression** | `string` | ✅ | Cron expression (e.g., "0 0 * * *" for daily at midnight) | +| **timezone** | `string` | optional | Timezone for cron execution (e.g., "America/New_York") | + +--- + +## IntervalSchedule + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **type** | `string` | ✅ | | +| **intervalMs** | `integer` | ✅ | Interval in milliseconds | + +--- + +## Job + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | ✅ | Unique job identifier | +| **name** | `string` | ✅ | Job name (snake_case) | +| **schedule** | `object \| object \| object` | ✅ | Job schedule configuration | +| **retryPolicy** | `object` | optional | Retry policy configuration | +| **timeout** | `integer` | optional | Timeout in milliseconds | +| **enabled** | `boolean` | optional | Whether the job is enabled | + +--- + +## JobExecution + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **jobId** | `string` | ✅ | Job identifier | +| **startedAt** | `string` | ✅ | ISO 8601 datetime when execution started | +| **completedAt** | `string` | optional | ISO 8601 datetime when execution completed | +| **status** | `Enum<'running' \| 'success' \| 'failed' \| 'timeout'>` | ✅ | Execution status | +| **error** | `string` | optional | Error message if failed | +| **duration** | `integer` | optional | Execution duration in milliseconds | + +--- + +## JobExecutionStatus + +### Allowed Values + +* `running` +* `success` +* `failed` +* `timeout` + +--- + +## OnceSchedule + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **type** | `string` | ✅ | | +| **at** | `string` | ✅ | ISO 8601 datetime when to execute | + +--- + +## RetryPolicy + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **maxRetries** | `integer` | optional | Maximum number of retry attempts | +| **backoffMs** | `integer` | optional | Initial backoff delay in milliseconds | +| **backoffMultiplier** | `number` | optional | Multiplier for exponential backoff | + +--- + +## Schedule + diff --git a/content/docs/references/system/job/CronSchedule.mdx b/content/docs/references/system/job/CronSchedule.mdx deleted file mode 100644 index 805be3270..000000000 --- a/content/docs/references/system/job/CronSchedule.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: CronSchedule -description: CronSchedule Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **expression** | `string` | ✅ | Cron expression (e.g., "0 0 * * *" for daily at midnight) | -| **timezone** | `string` | optional | Timezone for cron execution (e.g., "America/New_York") | diff --git a/content/docs/references/system/job/IntervalSchedule.mdx b/content/docs/references/system/job/IntervalSchedule.mdx deleted file mode 100644 index e73d6f8ec..000000000 --- a/content/docs/references/system/job/IntervalSchedule.mdx +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: IntervalSchedule -description: IntervalSchedule Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **intervalMs** | `integer` | ✅ | Interval in milliseconds | diff --git a/content/docs/references/system/job/Job.mdx b/content/docs/references/system/job/Job.mdx deleted file mode 100644 index 43c9affe1..000000000 --- a/content/docs/references/system/job/Job.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: Job -description: Job Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Unique job identifier | -| **name** | `string` | ✅ | Job name (snake_case) | -| **schedule** | `object \| object \| object` | ✅ | Job schedule configuration | -| **retryPolicy** | `object` | optional | Retry policy configuration | -| **timeout** | `integer` | optional | Timeout in milliseconds | -| **enabled** | `boolean` | optional | Whether the job is enabled | diff --git a/content/docs/references/system/job/JobExecution.mdx b/content/docs/references/system/job/JobExecution.mdx deleted file mode 100644 index e1921929c..000000000 --- a/content/docs/references/system/job/JobExecution.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: JobExecution -description: JobExecution Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **jobId** | `string` | ✅ | Job identifier | -| **startedAt** | `string` | ✅ | ISO 8601 datetime when execution started | -| **completedAt** | `string` | optional | ISO 8601 datetime when execution completed | -| **status** | `Enum<'running' \| 'success' \| 'failed' \| 'timeout'>` | ✅ | Execution status | -| **error** | `string` | optional | Error message if failed | -| **duration** | `integer` | optional | Execution duration in milliseconds | diff --git a/content/docs/references/system/job/JobExecutionStatus.mdx b/content/docs/references/system/job/JobExecutionStatus.mdx deleted file mode 100644 index 32b3eefad..000000000 --- a/content/docs/references/system/job/JobExecutionStatus.mdx +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: JobExecutionStatus -description: JobExecutionStatus Schema Reference ---- - -## Allowed Values - -* `running` -* `success` -* `failed` -* `timeout` \ No newline at end of file diff --git a/content/docs/references/system/job/OnceSchedule.mdx b/content/docs/references/system/job/OnceSchedule.mdx deleted file mode 100644 index f3b49aa22..000000000 --- a/content/docs/references/system/job/OnceSchedule.mdx +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: OnceSchedule -description: OnceSchedule Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **at** | `string` | ✅ | ISO 8601 datetime when to execute | diff --git a/content/docs/references/system/job/RetryPolicy.mdx b/content/docs/references/system/job/RetryPolicy.mdx deleted file mode 100644 index 5277b4dfe..000000000 --- a/content/docs/references/system/job/RetryPolicy.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: RetryPolicy -description: RetryPolicy Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **maxRetries** | `integer` | optional | Maximum number of retry attempts | -| **backoffMs** | `integer` | optional | Initial backoff delay in milliseconds | -| **backoffMultiplier** | `number` | optional | Multiplier for exponential backoff | diff --git a/content/docs/references/system/job/Schedule.mdx b/content/docs/references/system/job/Schedule.mdx deleted file mode 100644 index 87b18bed7..000000000 --- a/content/docs/references/system/job/Schedule.mdx +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: Schedule -description: Schedule Schema Reference ---- - diff --git a/content/docs/references/system/job/meta.json b/content/docs/references/system/job/meta.json deleted file mode 100644 index b99cc8c03..000000000 --- a/content/docs/references/system/job/meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "title": "Job" -} \ No newline at end of file diff --git a/content/docs/references/system/logger.mdx b/content/docs/references/system/logger.mdx new file mode 100644 index 000000000..f96d47863 --- /dev/null +++ b/content/docs/references/system/logger.mdx @@ -0,0 +1,80 @@ +--- +title: Logger +description: Logger protocol schemas +--- + +# Logger + + +**Source:** `packages/spec/src/system/logger.zod.ts` + + +## TypeScript Usage + +```typescript +import { LogEntrySchema, LogFormatSchema, LogLevelSchema, LoggerConfigSchema } from '@objectstack/spec/system'; +import type { LogEntry, LogFormat, LogLevel, LoggerConfig } from '@objectstack/spec/system'; + +// Validate data +const result = LogEntrySchema.parse(data); +``` + +--- + +## LogEntry + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **timestamp** | `string` | ✅ | ISO 8601 timestamp | +| **level** | `Enum<'debug' \| 'info' \| 'warn' \| 'error' \| 'fatal'>` | ✅ | Log severity level | +| **message** | `string` | ✅ | Log message | +| **context** | `Record` | optional | Structured context data | +| **error** | `Record` | optional | Error object if present | +| **traceId** | `string` | optional | Distributed trace ID | +| **spanId** | `string` | optional | Span ID | +| **service** | `string` | optional | Service name | +| **component** | `string` | optional | Component name (e.g. plugin id) | + +--- + +## LogFormat + +Log output format + +### Allowed Values + +* `json` +* `text` +* `pretty` + +--- + +## LogLevel + +Log severity level + +### Allowed Values + +* `debug` +* `info` +* `warn` +* `error` +* `fatal` + +--- + +## LoggerConfig + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **level** | `Enum<'debug' \| 'info' \| 'warn' \| 'error' \| 'fatal'>` | optional | Log severity level | +| **format** | `Enum<'json' \| 'text' \| 'pretty'>` | optional | Log output format | +| **redact** | `string[]` | optional | Keys to redact from log context | +| **sourceLocation** | `boolean` | optional | Include file and line number | +| **file** | `string` | optional | Path to log file | +| **rotation** | `object` | optional | | + diff --git a/content/docs/references/system/logger/LogEntry.mdx b/content/docs/references/system/logger/LogEntry.mdx deleted file mode 100644 index 14fb533f9..000000000 --- a/content/docs/references/system/logger/LogEntry.mdx +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: LogEntry -description: LogEntry Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **timestamp** | `string` | ✅ | ISO 8601 timestamp | -| **level** | `Enum<'debug' \| 'info' \| 'warn' \| 'error' \| 'fatal'>` | ✅ | Log severity level | -| **message** | `string` | ✅ | Log message | -| **context** | `Record` | optional | Structured context data | -| **error** | `Record` | optional | Error object if present | -| **traceId** | `string` | optional | Distributed trace ID | -| **spanId** | `string` | optional | Span ID | -| **service** | `string` | optional | Service name | -| **component** | `string` | optional | Component name (e.g. plugin id) | diff --git a/content/docs/references/system/logger/LogFormat.mdx b/content/docs/references/system/logger/LogFormat.mdx deleted file mode 100644 index 78b174802..000000000 --- a/content/docs/references/system/logger/LogFormat.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: LogFormat -description: Log output format ---- - -Log output format - -## Allowed Values - -* `json` -* `text` -* `pretty` \ No newline at end of file diff --git a/content/docs/references/system/logger/LogLevel.mdx b/content/docs/references/system/logger/LogLevel.mdx deleted file mode 100644 index c8790054b..000000000 --- a/content/docs/references/system/logger/LogLevel.mdx +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: LogLevel -description: Log severity level ---- - -Log severity level - -## Allowed Values - -* `debug` -* `info` -* `warn` -* `error` -* `fatal` \ No newline at end of file diff --git a/content/docs/references/system/logger/LoggerConfig.mdx b/content/docs/references/system/logger/LoggerConfig.mdx deleted file mode 100644 index 2a35ba499..000000000 --- a/content/docs/references/system/logger/LoggerConfig.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: LoggerConfig -description: LoggerConfig Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **level** | `Enum<'debug' \| 'info' \| 'warn' \| 'error' \| 'fatal'>` | optional | Log severity level | -| **format** | `Enum<'json' \| 'text' \| 'pretty'>` | optional | Log output format | -| **redact** | `string[]` | optional | Keys to redact from log context | -| **sourceLocation** | `boolean` | optional | Include file and line number | -| **file** | `string` | optional | Path to log file | -| **rotation** | `object` | optional | | diff --git a/content/docs/references/system/logger/meta.json b/content/docs/references/system/logger/meta.json deleted file mode 100644 index 55e960b67..000000000 --- a/content/docs/references/system/logger/meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "title": "Logger" -} \ No newline at end of file diff --git a/content/docs/references/system/manifest/Manifest.mdx b/content/docs/references/system/manifest.mdx similarity index 74% rename from content/docs/references/system/manifest/Manifest.mdx rename to content/docs/references/system/manifest.mdx index f4633e993..a13db0918 100644 --- a/content/docs/references/system/manifest/Manifest.mdx +++ b/content/docs/references/system/manifest.mdx @@ -1,9 +1,29 @@ --- title: Manifest -description: Manifest Schema Reference +description: Manifest protocol schemas --- -## Properties +# Manifest + + +**Source:** `packages/spec/src/system/manifest.zod.ts` + + +## TypeScript Usage + +```typescript +import { ManifestSchema } from '@objectstack/spec/system'; +import type { Manifest } from '@objectstack/spec/system'; + +// Validate data +const result = ManifestSchema.parse(data); +``` + +--- + +## Manifest + +### Properties | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | @@ -20,3 +40,4 @@ description: Manifest Schema Reference | **contributes** | `object` | optional | Platform contributions | | **data** | `object[]` | optional | Initial seed data | | **extensions** | `Record` | optional | Extension points and contributions | + diff --git a/content/docs/references/system/manifest/meta.json b/content/docs/references/system/manifest/meta.json deleted file mode 100644 index 698ba3541..000000000 --- a/content/docs/references/system/manifest/meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "title": "Manifest" -} \ No newline at end of file diff --git a/content/docs/references/system/misc.mdx b/content/docs/references/system/misc.mdx new file mode 100644 index 000000000..a7e0b7ff2 --- /dev/null +++ b/content/docs/references/system/misc.mdx @@ -0,0 +1,67 @@ +--- +title: Misc +description: Misc protocol schemas +--- + +# Misc + + +**Source:** `packages/spec/src/system/misc.zod.ts` + + +## TypeScript Usage + +```typescript +import { MongoConfigSchema, PostgresConfigSchema } from '@objectstack/spec/system'; +import type { MongoConfig, PostgresConfig } from '@objectstack/spec/system'; + +// Validate data +const result = MongoConfigSchema.parse(data); +``` + +--- + +## MongoConfig + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **url** | `string` | optional | Connection URI | +| **database** | `string` | ✅ | Database Name | +| **host** | `string` | optional | Host address | +| **port** | `number` | optional | Port number | +| **username** | `string` | optional | Auth User | +| **password** | `string` | optional | Auth Password | +| **authSource** | `string` | optional | Authentication Database | +| **ssl** | `boolean` | optional | Enable SSL | +| **replicaSet** | `string` | optional | Replica Set Name | +| **readPreference** | `Enum<'primary' \| 'primaryPreferred' \| 'secondary' \| 'secondaryPreferred' \| 'nearest'>` | optional | Read Preference | +| **maxPoolSize** | `number` | optional | Max Connection Pool Size | +| **minPoolSize** | `number` | optional | Min Connection Pool Size | +| **connectTimeoutMS** | `number` | optional | Connection Timeout (ms) | +| **socketTimeoutMS** | `number` | optional | Socket Timeout (ms) | + +--- + +## PostgresConfig + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **url** | `string` | optional | Connection URI | +| **database** | `string` | ✅ | Database Name | +| **host** | `string` | optional | Host address | +| **port** | `number` | optional | Port number | +| **username** | `string` | optional | Auth User | +| **password** | `string` | optional | Auth Password | +| **schema** | `string` | optional | Default Schema | +| **ssl** | `boolean \| object` | optional | Enable SSL | +| **applicationName** | `string` | optional | Application Name | +| **max** | `number` | optional | Max Pool Size | +| **min** | `number` | optional | Min Pool Size | +| **idleTimeoutMillis** | `number` | optional | Idle Timeout (ms) | +| **connectionTimeoutMillis** | `number` | optional | Connection Timeout (ms) | +| **statementTimeout** | `number` | optional | Statement Timeout (ms) | + diff --git a/content/docs/references/system/plugin.mdx b/content/docs/references/system/plugin.mdx new file mode 100644 index 000000000..78c0b5f99 --- /dev/null +++ b/content/docs/references/system/plugin.mdx @@ -0,0 +1,140 @@ +--- +title: Plugin +description: Plugin protocol schemas +--- + +# Plugin + + +**Source:** `packages/spec/src/system/plugin.zod.ts` + + +## TypeScript Usage + +```typescript +import { I18nContextSchema, LoggerSchema, ObjectQLClientSchema, PluginSchema, PluginContextSchema, PluginLifecycleSchema, RouterSchema, SchedulerSchema, ScopedStorageSchema, SystemAPISchema } from '@objectstack/spec/system'; +import type { I18nContext, Logger, ObjectQLClient, Plugin, PluginContext, PluginLifecycle, Router, Scheduler, ScopedStorage, SystemAPI } from '@objectstack/spec/system'; + +// Validate data +const result = I18nContextSchema.parse(data); +``` + +--- + +## I18nContext + +Internationalization Helper + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | + +--- + +## Logger + +Structured Logger + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **debug** | `any` | optional | (message: string, ...meta: any[]) => void | +| **info** | `any` | optional | (message: string, ...meta: any[]) => void | +| **warn** | `any` | optional | (message: string, ...meta: any[]) => void | +| **error** | `any` | optional | (message: string, ...meta: any[]) => void | + +--- + +## ObjectQLClient + +ObjectQL Data Access Client + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | + +--- + +## Plugin + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | optional | Plugin identifier | +| **version** | `string` | optional | Plugin version | + +--- + +## PluginContext + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **ql** | `object` | ✅ | ObjectQL Data Access Client | +| **os** | `object` | ✅ | Access to System Core | +| **logger** | `object` | ✅ | Structured Logger | +| **storage** | `object` | ✅ | Plugin Scoped Data Storage (KV) | +| **i18n** | `object` | ✅ | Internationalization Helper | +| **metadata** | `any` | optional | Metadata registry | +| **events** | `any` | optional | Event bus | +| **app** | `object` | ✅ | App Runtime Capabilities | +| **drivers** | `object` | ✅ | Driver Management | + +--- + +## PluginLifecycle + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | + +--- + +## Router + +HTTP Router Interface + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | + +--- + +## Scheduler + +Job Scheduler Interface + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | + +--- + +## ScopedStorage + +Plugin Scoped Data Storage (KV) + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | + +--- + +## SystemAPI + +Access to System Core + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | + diff --git a/content/docs/references/system/plugin/I18nContext.mdx b/content/docs/references/system/plugin/I18nContext.mdx deleted file mode 100644 index 7f03c9198..000000000 --- a/content/docs/references/system/plugin/I18nContext.mdx +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: I18nContext -description: Internationalization Helper ---- - -Internationalization Helper - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | diff --git a/content/docs/references/system/plugin/Logger.mdx b/content/docs/references/system/plugin/Logger.mdx deleted file mode 100644 index 90febc850..000000000 --- a/content/docs/references/system/plugin/Logger.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: Logger -description: Structured Logger ---- - -Structured Logger - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **debug** | `any` | optional | (message: string, ...meta: any[]) => void | -| **info** | `any` | optional | (message: string, ...meta: any[]) => void | -| **warn** | `any` | optional | (message: string, ...meta: any[]) => void | -| **error** | `any` | optional | (message: string, ...meta: any[]) => void | diff --git a/content/docs/references/system/plugin/ObjectQLClient.mdx b/content/docs/references/system/plugin/ObjectQLClient.mdx deleted file mode 100644 index dddd5e862..000000000 --- a/content/docs/references/system/plugin/ObjectQLClient.mdx +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: ObjectQLClient -description: ObjectQL Data Access Client ---- - -ObjectQL Data Access Client - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | diff --git a/content/docs/references/system/plugin/Plugin.mdx b/content/docs/references/system/plugin/Plugin.mdx deleted file mode 100644 index 00d48a3fe..000000000 --- a/content/docs/references/system/plugin/Plugin.mdx +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Plugin -description: Plugin Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | optional | Plugin identifier | -| **version** | `string` | optional | Plugin version | diff --git a/content/docs/references/system/plugin/PluginContext.mdx b/content/docs/references/system/plugin/PluginContext.mdx deleted file mode 100644 index 63eaee7c1..000000000 --- a/content/docs/references/system/plugin/PluginContext.mdx +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: PluginContext -description: PluginContext Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **ql** | `object` | ✅ | ObjectQL Data Access Client | -| **os** | `object` | ✅ | Access to System Core | -| **logger** | `object` | ✅ | Structured Logger | -| **storage** | `object` | ✅ | Plugin Scoped Data Storage (KV) | -| **i18n** | `object` | ✅ | Internationalization Helper | -| **metadata** | `any` | optional | Metadata registry | -| **events** | `any` | optional | Event bus | -| **app** | `object` | ✅ | App Runtime Capabilities | -| **drivers** | `object` | ✅ | Driver Management | diff --git a/content/docs/references/system/plugin/PluginLifecycle.mdx b/content/docs/references/system/plugin/PluginLifecycle.mdx deleted file mode 100644 index 3e4cbb022..000000000 --- a/content/docs/references/system/plugin/PluginLifecycle.mdx +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: PluginLifecycle -description: PluginLifecycle Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | diff --git a/content/docs/references/system/plugin/Router.mdx b/content/docs/references/system/plugin/Router.mdx deleted file mode 100644 index 5960be2f8..000000000 --- a/content/docs/references/system/plugin/Router.mdx +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Router -description: HTTP Router Interface ---- - -HTTP Router Interface - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | diff --git a/content/docs/references/system/plugin/Scheduler.mdx b/content/docs/references/system/plugin/Scheduler.mdx deleted file mode 100644 index 60390dc1d..000000000 --- a/content/docs/references/system/plugin/Scheduler.mdx +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Scheduler -description: Job Scheduler Interface ---- - -Job Scheduler Interface - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | diff --git a/content/docs/references/system/plugin/ScopedStorage.mdx b/content/docs/references/system/plugin/ScopedStorage.mdx deleted file mode 100644 index 9ec40e6c1..000000000 --- a/content/docs/references/system/plugin/ScopedStorage.mdx +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: ScopedStorage -description: Plugin Scoped Data Storage (KV) ---- - -Plugin Scoped Data Storage (KV) - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | diff --git a/content/docs/references/system/plugin/SystemAPI.mdx b/content/docs/references/system/plugin/SystemAPI.mdx deleted file mode 100644 index 2ad8c9166..000000000 --- a/content/docs/references/system/plugin/SystemAPI.mdx +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: SystemAPI -description: Access to System Core ---- - -Access to System Core - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | diff --git a/content/docs/references/system/plugin/meta.json b/content/docs/references/system/plugin/meta.json deleted file mode 100644 index b2d5705b5..000000000 --- a/content/docs/references/system/plugin/meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "title": "Plugin" -} \ No newline at end of file diff --git a/content/docs/references/system/scoped-storage.mdx b/content/docs/references/system/scoped-storage.mdx new file mode 100644 index 000000000..71e455bd8 --- /dev/null +++ b/content/docs/references/system/scoped-storage.mdx @@ -0,0 +1,79 @@ +--- +title: Scoped Storage +description: Scoped Storage protocol schemas +--- + +# Scoped Storage + + +**Source:** `packages/spec/src/system/scoped-storage.zod.ts` + + +## TypeScript Usage + +```typescript +import { FileMetadataSchema, ScopedStorageConfigSchema, StorageAdapterTypeSchema, StorageScopeSchema } from '@objectstack/spec/system'; +import type { FileMetadata, ScopedStorageConfig, StorageAdapterType, StorageScope } from '@objectstack/spec/system'; + +// Validate data +const result = FileMetadataSchema.parse(data); +``` + +--- + +## FileMetadata + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **path** | `string` | ✅ | | +| **name** | `string` | ✅ | | +| **size** | `integer` | ✅ | | +| **mimeType** | `string` | ✅ | | +| **lastModified** | `string` | ✅ | | +| **created** | `string` | ✅ | | +| **etag** | `string` | optional | | + +--- + +## ScopedStorageConfig + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **scope** | `Enum<'temp' \| 'cache' \| 'data' \| 'logs' \| 'config' \| 'public'>` | ✅ | Generic storage scope classification | +| **adapter** | `Enum<'local' \| 'memory' \| 's3' \| 'gcs' \| 'azure' \| 'gridfs'>` | optional | | +| **location** | `string` | ✅ | Root path (local) or Bucket name (remote) | +| **options** | `Record` | optional | Driver specific options (region, endpoint, etc) | +| **quota** | `integer` | optional | Max size in bytes | + +--- + +## StorageAdapterType + +### Allowed Values + +* `local` +* `memory` +* `s3` +* `gcs` +* `azure` +* `gridfs` + +--- + +## StorageScope + +Generic storage scope classification + +### Allowed Values + +* `temp` +* `cache` +* `data` +* `logs` +* `config` +* `public` + diff --git a/content/docs/references/system/scoped-storage/FileMetadata.mdx b/content/docs/references/system/scoped-storage/FileMetadata.mdx deleted file mode 100644 index 9a06a697b..000000000 --- a/content/docs/references/system/scoped-storage/FileMetadata.mdx +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: FileMetadata -description: FileMetadata Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **path** | `string` | ✅ | | -| **name** | `string` | ✅ | | -| **size** | `integer` | ✅ | | -| **mimeType** | `string` | ✅ | | -| **lastModified** | `string` | ✅ | | -| **created** | `string` | ✅ | | -| **etag** | `string` | optional | | diff --git a/content/docs/references/system/scoped-storage/ScopedStorageConfig.mdx b/content/docs/references/system/scoped-storage/ScopedStorageConfig.mdx deleted file mode 100644 index d06945154..000000000 --- a/content/docs/references/system/scoped-storage/ScopedStorageConfig.mdx +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: ScopedStorageConfig -description: ScopedStorageConfig Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **scope** | `Enum<'temp' \| 'cache' \| 'data' \| 'logs' \| 'config' \| 'public'>` | ✅ | Generic storage scope classification | -| **adapter** | `Enum<'local' \| 'memory' \| 's3' \| 'gcs' \| 'azure' \| 'gridfs'>` | optional | | -| **location** | `string` | ✅ | Root path (local) or Bucket name (remote) | -| **options** | `Record` | optional | Driver specific options (region, endpoint, etc) | -| **quota** | `integer` | optional | Max size in bytes | diff --git a/content/docs/references/system/scoped-storage/StorageAdapterType.mdx b/content/docs/references/system/scoped-storage/StorageAdapterType.mdx deleted file mode 100644 index a614be9ee..000000000 --- a/content/docs/references/system/scoped-storage/StorageAdapterType.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: StorageAdapterType -description: StorageAdapterType Schema Reference ---- - -## Allowed Values - -* `local` -* `memory` -* `s3` -* `gcs` -* `azure` -* `gridfs` \ No newline at end of file diff --git a/content/docs/references/system/scoped-storage/StorageScope.mdx b/content/docs/references/system/scoped-storage/StorageScope.mdx deleted file mode 100644 index f155f1e81..000000000 --- a/content/docs/references/system/scoped-storage/StorageScope.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: StorageScope -description: Generic storage scope classification ---- - -Generic storage scope classification - -## Allowed Values - -* `temp` -* `cache` -* `data` -* `logs` -* `config` -* `public` \ No newline at end of file diff --git a/content/docs/references/system/scoped-storage/meta.json b/content/docs/references/system/scoped-storage/meta.json deleted file mode 100644 index 8a0466cfb..000000000 --- a/content/docs/references/system/scoped-storage/meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "title": "Scoped Storage" -} \ No newline at end of file diff --git a/content/docs/references/system/translation.mdx b/content/docs/references/system/translation.mdx new file mode 100644 index 000000000..62690d173 --- /dev/null +++ b/content/docs/references/system/translation.mdx @@ -0,0 +1,43 @@ +--- +title: Translation +description: Translation protocol schemas +--- + +# Translation + + +**Source:** `packages/spec/src/system/translation.zod.ts` + + +## TypeScript Usage + +```typescript +import { LocaleSchema, TranslationBundleSchema, TranslationDataSchema } from '@objectstack/spec/system'; +import type { Locale, TranslationBundle, TranslationData } from '@objectstack/spec/system'; + +// Validate data +const result = LocaleSchema.parse(data); +``` + +--- + +## Locale + +BCP-47 Language Tag (e.g. en-US, zh-CN) + +--- + +## TranslationBundle + +--- + +## TranslationData + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **objects** | `Record` | optional | | +| **apps** | `Record` | optional | | +| **messages** | `Record` | optional | | + diff --git a/content/docs/references/system/translation/Locale.mdx b/content/docs/references/system/translation/Locale.mdx deleted file mode 100644 index a930a875d..000000000 --- a/content/docs/references/system/translation/Locale.mdx +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: Locale -description: BCP-47 Language Tag (e.g. en-US, zh-CN) ---- - -BCP-47 Language Tag (e.g. en-US, zh-CN) - diff --git a/content/docs/references/system/translation/TranslationBundle.mdx b/content/docs/references/system/translation/TranslationBundle.mdx deleted file mode 100644 index 937c54f56..000000000 --- a/content/docs/references/system/translation/TranslationBundle.mdx +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: TranslationBundle -description: TranslationBundle Schema Reference ---- - diff --git a/content/docs/references/system/translation/TranslationData.mdx b/content/docs/references/system/translation/TranslationData.mdx deleted file mode 100644 index 95a354a6e..000000000 --- a/content/docs/references/system/translation/TranslationData.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: TranslationData -description: TranslationData Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **objects** | `Record` | optional | | -| **apps** | `Record` | optional | | -| **messages** | `Record` | optional | | diff --git a/content/docs/references/system/translation/meta.json b/content/docs/references/system/translation/meta.json deleted file mode 100644 index 3e61aa3e8..000000000 --- a/content/docs/references/system/translation/meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "title": "Translation" -} \ No newline at end of file diff --git a/content/docs/references/ui/action/Action.mdx b/content/docs/references/ui/action.mdx similarity index 50% rename from content/docs/references/ui/action/Action.mdx rename to content/docs/references/ui/action.mdx index 6ff80d0c6..6f3f3c03b 100644 --- a/content/docs/references/ui/action/Action.mdx +++ b/content/docs/references/ui/action.mdx @@ -1,9 +1,29 @@ --- title: Action -description: Action Schema Reference +description: Action protocol schemas --- -## Properties +# Action + + +**Source:** `packages/spec/src/ui/action.zod.ts` + + +## TypeScript Usage + +```typescript +import { ActionSchema, ActionParamSchema } from '@objectstack/spec/ui'; +import type { Action, ActionParam } from '@objectstack/spec/ui'; + +// Validate data +const result = ActionSchema.parse(data); +``` + +--- + +## Action + +### Properties | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | @@ -21,3 +41,18 @@ description: Action Schema Reference | **successMessage** | `string` | optional | Success message to show after execution | | **refreshAfter** | `boolean` | optional | Refresh view after execution | | **visible** | `string` | optional | Formula returning boolean | + +--- + +## ActionParam + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | | +| **label** | `string` | ✅ | | +| **type** | `Enum<'text' \| 'textarea' \| 'email' \| 'url' \| 'phone' \| 'password' \| 'markdown' \| 'html' \| 'richtext' \| 'number' \| 'currency' \| 'percent' \| 'date' \| 'datetime' \| 'time' \| 'boolean' \| 'toggle' \| 'select' \| 'multiselect' \| 'radio' \| 'checkboxes' \| 'lookup' \| 'master_detail' \| 'tree' \| 'image' \| 'file' \| 'avatar' \| 'video' \| 'audio' \| 'formula' \| 'summary' \| 'autonumber' \| 'location' \| 'address' \| 'code' \| 'json' \| 'color' \| 'rating' \| 'slider' \| 'signature' \| 'qrcode' \| 'progress' \| 'tags' \| 'vector'>` | ✅ | | +| **required** | `boolean` | optional | | +| **options** | `object[]` | optional | | + diff --git a/content/docs/references/ui/action/ActionParam.mdx b/content/docs/references/ui/action/ActionParam.mdx deleted file mode 100644 index bc61561f3..000000000 --- a/content/docs/references/ui/action/ActionParam.mdx +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: ActionParam -description: ActionParam Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | | -| **label** | `string` | ✅ | | -| **type** | `Enum<'text' \| 'textarea' \| 'email' \| 'url' \| 'phone' \| 'password' \| 'markdown' \| 'html' \| 'richtext' \| 'number' \| 'currency' \| 'percent' \| 'date' \| 'datetime' \| 'time' \| 'boolean' \| 'toggle' \| 'select' \| 'multiselect' \| 'radio' \| 'checkboxes' \| 'lookup' \| 'master_detail' \| 'tree' \| 'image' \| 'file' \| 'avatar' \| 'video' \| 'audio' \| 'formula' \| 'summary' \| 'autonumber' \| 'location' \| 'address' \| 'code' \| 'json' \| 'color' \| 'rating' \| 'slider' \| 'signature' \| 'qrcode' \| 'progress' \| 'tags' \| 'vector'>` | ✅ | | -| **required** | `boolean` | optional | | -| **options** | `object[]` | optional | | diff --git a/content/docs/references/ui/action/meta.json b/content/docs/references/ui/action/meta.json deleted file mode 100644 index 98e37fd51..000000000 --- a/content/docs/references/ui/action/meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "title": "Action" -} \ No newline at end of file diff --git a/content/docs/references/ui/app.mdx b/content/docs/references/ui/app.mdx new file mode 100644 index 000000000..1ba2822e1 --- /dev/null +++ b/content/docs/references/ui/app.mdx @@ -0,0 +1,137 @@ +--- +title: App +description: App protocol schemas +--- + +# App + + +**Source:** `packages/spec/src/ui/app.zod.ts` + + +## TypeScript Usage + +```typescript +import { AppSchema, AppBrandingSchema, DashboardNavItemSchema, GroupNavItemSchema, NavigationItemSchema, ObjectNavItemSchema, PageNavItemSchema, UrlNavItemSchema } from '@objectstack/spec/ui'; +import type { App, AppBranding, DashboardNavItem, GroupNavItem, NavigationItem, ObjectNavItem, PageNavItem, UrlNavItem } from '@objectstack/spec/ui'; + +// Validate data +const result = AppSchema.parse(data); +``` + +--- + +## App + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | App unique machine name (lowercase snake_case) | +| **label** | `string` | ✅ | App display label | +| **version** | `string` | optional | App version | +| **description** | `string` | optional | App description | +| **icon** | `string` | optional | App icon used in the App Launcher | +| **branding** | `object` | optional | App-specific branding | +| **active** | `boolean` | optional | Whether the app is enabled | +| **isDefault** | `boolean` | optional | Is default app | +| **navigation** | `object \| object \| object \| object \| object[]` | optional | Structured navigation menu tree | +| **homePageId** | `string` | optional | ID of the navigation item to serve as landing page | +| **requiredPermissions** | `string[]` | optional | Permissions required to access this app | +| **objects** | `any[]` | optional | Objects belonging to this app | +| **apis** | `any[]` | optional | Custom APIs belonging to this app | + +--- + +## AppBranding + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **primaryColor** | `string` | optional | Primary theme color hex code | +| **logo** | `string` | optional | Custom logo URL for this app | +| **favicon** | `string` | optional | Custom favicon URL for this app | + +--- + +## DashboardNavItem + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | ✅ | Unique identifier for this navigation item (lowercase snake_case) | +| **label** | `string` | ✅ | Display proper label | +| **icon** | `string` | optional | Icon name | +| **visible** | `string` | optional | Visibility formula condition | +| **type** | `string` | ✅ | | +| **dashboardName** | `string` | ✅ | Target dashboard name | + +--- + +## GroupNavItem + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | ✅ | Unique identifier for this navigation item (lowercase snake_case) | +| **label** | `string` | ✅ | Display proper label | +| **icon** | `string` | optional | Icon name | +| **visible** | `string` | optional | Visibility formula condition | +| **type** | `string` | ✅ | | +| **expanded** | `boolean` | optional | Default expansion state in sidebar | + +--- + +## NavigationItem + +--- + +## ObjectNavItem + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | ✅ | Unique identifier for this navigation item (lowercase snake_case) | +| **label** | `string` | ✅ | Display proper label | +| **icon** | `string` | optional | Icon name | +| **visible** | `string` | optional | Visibility formula condition | +| **type** | `string` | ✅ | | +| **objectName** | `string` | ✅ | Target object name | +| **viewName** | `string` | optional | Default list view to open. Defaults to "all" | + +--- + +## PageNavItem + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | ✅ | Unique identifier for this navigation item (lowercase snake_case) | +| **label** | `string` | ✅ | Display proper label | +| **icon** | `string` | optional | Icon name | +| **visible** | `string` | optional | Visibility formula condition | +| **type** | `string` | ✅ | | +| **pageName** | `string` | ✅ | Target custom page component name | +| **params** | `Record` | optional | Parameters passed to the page context | + +--- + +## UrlNavItem + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | ✅ | Unique identifier for this navigation item (lowercase snake_case) | +| **label** | `string` | ✅ | Display proper label | +| **icon** | `string` | optional | Icon name | +| **visible** | `string` | optional | Visibility formula condition | +| **type** | `string` | ✅ | | +| **url** | `string` | ✅ | Target external URL | +| **target** | `Enum<'_self' \| '_blank'>` | optional | Link target window | + diff --git a/content/docs/references/ui/app/App.mdx b/content/docs/references/ui/app/App.mdx deleted file mode 100644 index 124d5d2a6..000000000 --- a/content/docs/references/ui/app/App.mdx +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: App -description: App Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | App unique machine name (lowercase snake_case) | -| **label** | `string` | ✅ | App display label | -| **version** | `string` | optional | App version | -| **description** | `string` | optional | App description | -| **icon** | `string` | optional | App icon used in the App Launcher | -| **branding** | `object` | optional | App-specific branding | -| **active** | `boolean` | optional | Whether the app is enabled | -| **isDefault** | `boolean` | optional | Is default app | -| **navigation** | `object \| object \| object \| object \| object[]` | optional | Structured navigation menu tree | -| **homePageId** | `string` | optional | ID of the navigation item to serve as landing page | -| **requiredPermissions** | `string[]` | optional | Permissions required to access this app | -| **objects** | `any[]` | optional | Objects belonging to this app | -| **apis** | `any[]` | optional | Custom APIs belonging to this app | diff --git a/content/docs/references/ui/app/AppBranding.mdx b/content/docs/references/ui/app/AppBranding.mdx deleted file mode 100644 index ff066bb0e..000000000 --- a/content/docs/references/ui/app/AppBranding.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: AppBranding -description: AppBranding Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **primaryColor** | `string` | optional | Primary theme color hex code | -| **logo** | `string` | optional | Custom logo URL for this app | -| **favicon** | `string` | optional | Custom favicon URL for this app | diff --git a/content/docs/references/ui/app/DashboardNavItem.mdx b/content/docs/references/ui/app/DashboardNavItem.mdx deleted file mode 100644 index 06d8c61d4..000000000 --- a/content/docs/references/ui/app/DashboardNavItem.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: DashboardNavItem -description: DashboardNavItem Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Unique identifier for this navigation item (lowercase snake_case) | -| **label** | `string` | ✅ | Display proper label | -| **icon** | `string` | optional | Icon name | -| **visible** | `string` | optional | Visibility formula condition | -| **type** | `string` | ✅ | | -| **dashboardName** | `string` | ✅ | Target dashboard name | diff --git a/content/docs/references/ui/app/GroupNavItem.mdx b/content/docs/references/ui/app/GroupNavItem.mdx deleted file mode 100644 index a336fee27..000000000 --- a/content/docs/references/ui/app/GroupNavItem.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: GroupNavItem -description: GroupNavItem Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Unique identifier for this navigation item (lowercase snake_case) | -| **label** | `string` | ✅ | Display proper label | -| **icon** | `string` | optional | Icon name | -| **visible** | `string` | optional | Visibility formula condition | -| **type** | `string` | ✅ | | -| **expanded** | `boolean` | optional | Default expansion state in sidebar | diff --git a/content/docs/references/ui/app/NavigationItem.mdx b/content/docs/references/ui/app/NavigationItem.mdx deleted file mode 100644 index 159d66648..000000000 --- a/content/docs/references/ui/app/NavigationItem.mdx +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: NavigationItem -description: NavigationItem Schema Reference ---- - diff --git a/content/docs/references/ui/app/ObjectNavItem.mdx b/content/docs/references/ui/app/ObjectNavItem.mdx deleted file mode 100644 index 080bed559..000000000 --- a/content/docs/references/ui/app/ObjectNavItem.mdx +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: ObjectNavItem -description: ObjectNavItem Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Unique identifier for this navigation item (lowercase snake_case) | -| **label** | `string` | ✅ | Display proper label | -| **icon** | `string` | optional | Icon name | -| **visible** | `string` | optional | Visibility formula condition | -| **type** | `string` | ✅ | | -| **objectName** | `string` | ✅ | Target object name | -| **viewName** | `string` | optional | Default list view to open. Defaults to "all" | diff --git a/content/docs/references/ui/app/PageNavItem.mdx b/content/docs/references/ui/app/PageNavItem.mdx deleted file mode 100644 index f30bf6b75..000000000 --- a/content/docs/references/ui/app/PageNavItem.mdx +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: PageNavItem -description: PageNavItem Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Unique identifier for this navigation item (lowercase snake_case) | -| **label** | `string` | ✅ | Display proper label | -| **icon** | `string` | optional | Icon name | -| **visible** | `string` | optional | Visibility formula condition | -| **type** | `string` | ✅ | | -| **pageName** | `string` | ✅ | Target custom page component name | -| **params** | `Record` | optional | Parameters passed to the page context | diff --git a/content/docs/references/ui/app/UrlNavItem.mdx b/content/docs/references/ui/app/UrlNavItem.mdx deleted file mode 100644 index f25bdd153..000000000 --- a/content/docs/references/ui/app/UrlNavItem.mdx +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: UrlNavItem -description: UrlNavItem Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Unique identifier for this navigation item (lowercase snake_case) | -| **label** | `string` | ✅ | Display proper label | -| **icon** | `string` | optional | Icon name | -| **visible** | `string` | optional | Visibility formula condition | -| **type** | `string` | ✅ | | -| **url** | `string` | ✅ | Target external URL | -| **target** | `Enum<'_self' \| '_blank'>` | optional | Link target window | diff --git a/content/docs/references/ui/app/meta.json b/content/docs/references/ui/app/meta.json deleted file mode 100644 index d13b942e6..000000000 --- a/content/docs/references/ui/app/meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "title": "App" -} \ No newline at end of file diff --git a/content/docs/references/ui/block/meta.json b/content/docs/references/ui/block/meta.json deleted file mode 100644 index 7321928ac..000000000 --- a/content/docs/references/ui/block/meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "title": "Block" -} \ No newline at end of file diff --git a/content/docs/references/ui/component.mdx b/content/docs/references/ui/component.mdx new file mode 100644 index 000000000..0a963db76 --- /dev/null +++ b/content/docs/references/ui/component.mdx @@ -0,0 +1,96 @@ +--- +title: Component +description: Component protocol schemas +--- + +# Component + + +**Source:** `packages/spec/src/ui/component.zod.ts` + + +## TypeScript Usage + +```typescript +import { PageCardPropsSchema, PageHeaderPropsSchema, PageTabsPropsSchema, RecordDetailsPropsSchema, RecordHighlightsPropsSchema, RecordRelatedListPropsSchema } from '@objectstack/spec/ui'; +import type { PageCardProps, PageHeaderProps, PageTabsProps, RecordDetailsProps, RecordHighlightsProps, RecordRelatedListProps } from '@objectstack/spec/ui'; + +// Validate data +const result = PageCardPropsSchema.parse(data); +``` + +--- + +## PageCardProps + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **title** | `string` | optional | | +| **bordered** | `boolean` | optional | | +| **actions** | `string[]` | optional | | +| **children** | `any[]` | ✅ | Card content | + +--- + +## PageHeaderProps + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **title** | `string` | ✅ | Page title | +| **subtitle** | `string` | optional | Page subtitle | +| **icon** | `string` | optional | Icon name | +| **breadcrumb** | `boolean` | optional | Show breadcrumb | +| **actions** | `string[]` | optional | Action IDs to show in header | + +--- + +## PageTabsProps + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **type** | `Enum<'line' \| 'card' \| 'pill'>` | optional | | +| **position** | `Enum<'top' \| 'left'>` | optional | | +| **items** | `object[]` | ✅ | | + +--- + +## RecordDetailsProps + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **columns** | `Enum<'1' \| '2' \| '3' \| '4'>` | optional | | +| **layout** | `Enum<'auto' \| 'custom'>` | optional | | +| **sections** | `string[]` | optional | Section IDs to show | + +--- + +## RecordHighlightsProps + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **fields** | `string[]` | ✅ | Key fields to highlights (max 7) | + +--- + +## RecordRelatedListProps + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **objectName** | `string` | ✅ | Related object name | +| **relationshipField** | `string` | ✅ | Field on related object that points to this record | +| **columns** | `string[]` | ✅ | Fields to display | +| **sort** | `string` | optional | | +| **limit** | `number` | optional | | + diff --git a/content/docs/references/ui/component/PageCardProps.mdx b/content/docs/references/ui/component/PageCardProps.mdx deleted file mode 100644 index c5f453484..000000000 --- a/content/docs/references/ui/component/PageCardProps.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: PageCardProps -description: PageCardProps Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **title** | `string` | optional | | -| **bordered** | `boolean` | optional | | -| **actions** | `string[]` | optional | | -| **children** | `any[]` | ✅ | Card content | diff --git a/content/docs/references/ui/component/PageHeaderProps.mdx b/content/docs/references/ui/component/PageHeaderProps.mdx deleted file mode 100644 index 9154f6895..000000000 --- a/content/docs/references/ui/component/PageHeaderProps.mdx +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: PageHeaderProps -description: PageHeaderProps Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **title** | `string` | ✅ | Page title | -| **subtitle** | `string` | optional | Page subtitle | -| **icon** | `string` | optional | Icon name | -| **breadcrumb** | `boolean` | optional | Show breadcrumb | -| **actions** | `string[]` | optional | Action IDs to show in header | diff --git a/content/docs/references/ui/component/PageTabsProps.mdx b/content/docs/references/ui/component/PageTabsProps.mdx deleted file mode 100644 index 71f9e9207..000000000 --- a/content/docs/references/ui/component/PageTabsProps.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: PageTabsProps -description: PageTabsProps Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `Enum<'line' \| 'card' \| 'pill'>` | optional | | -| **position** | `Enum<'top' \| 'left'>` | optional | | -| **items** | `object[]` | ✅ | | diff --git a/content/docs/references/ui/component/RecordDetailsProps.mdx b/content/docs/references/ui/component/RecordDetailsProps.mdx deleted file mode 100644 index e9e1f9326..000000000 --- a/content/docs/references/ui/component/RecordDetailsProps.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: RecordDetailsProps -description: RecordDetailsProps Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **columns** | `Enum<'1' \| '2' \| '3' \| '4'>` | optional | | -| **layout** | `Enum<'auto' \| 'custom'>` | optional | | -| **sections** | `string[]` | optional | Section IDs to show | diff --git a/content/docs/references/ui/component/RecordHighlightsProps.mdx b/content/docs/references/ui/component/RecordHighlightsProps.mdx deleted file mode 100644 index 690dbe6f0..000000000 --- a/content/docs/references/ui/component/RecordHighlightsProps.mdx +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: RecordHighlightsProps -description: RecordHighlightsProps Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **fields** | `string[]` | ✅ | Key fields to highlights (max 7) | diff --git a/content/docs/references/ui/component/RecordRelatedListProps.mdx b/content/docs/references/ui/component/RecordRelatedListProps.mdx deleted file mode 100644 index af02873eb..000000000 --- a/content/docs/references/ui/component/RecordRelatedListProps.mdx +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: RecordRelatedListProps -description: RecordRelatedListProps Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **objectName** | `string` | ✅ | Related object name | -| **relationshipField** | `string` | ✅ | Field on related object that points to this record | -| **columns** | `string[]` | ✅ | Fields to display | -| **sort** | `string` | optional | | -| **limit** | `number` | optional | | diff --git a/content/docs/references/ui/component/meta.json b/content/docs/references/ui/component/meta.json deleted file mode 100644 index fb9d9f60a..000000000 --- a/content/docs/references/ui/component/meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "title": "Component" -} \ No newline at end of file diff --git a/content/docs/references/ui/dashboard.mdx b/content/docs/references/ui/dashboard.mdx new file mode 100644 index 000000000..7b537a8c6 --- /dev/null +++ b/content/docs/references/ui/dashboard.mdx @@ -0,0 +1,75 @@ +--- +title: Dashboard +description: Dashboard protocol schemas +--- + +# Dashboard + + +**Source:** `packages/spec/src/ui/dashboard.zod.ts` + + +## TypeScript Usage + +```typescript +import { ChartTypeSchema, DashboardSchema, DashboardWidgetSchema } from '@objectstack/spec/ui'; +import type { ChartType, Dashboard, DashboardWidget } from '@objectstack/spec/ui'; + +// Validate data +const result = ChartTypeSchema.parse(data); +``` + +--- + +## ChartType + +### Allowed Values + +* `metric` +* `bar` +* `line` +* `pie` +* `donut` +* `gauge` +* `funnel` +* `radar` +* `scatter` +* `heatmap` +* `pivot` +* `table` +* `list` +* `text` +* `image` +* `frame` + +--- + +## Dashboard + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Dashboard unique name | +| **label** | `string` | ✅ | Dashboard label | +| **description** | `string` | optional | Dashboard description | +| **widgets** | `object[]` | ✅ | Widgets to display | + +--- + +## DashboardWidget + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **title** | `string` | optional | Widget title | +| **type** | `Enum<'metric' \| 'bar' \| 'line' \| 'pie' \| 'donut' \| 'gauge' \| 'funnel' \| 'radar' \| 'scatter' \| 'heatmap' \| 'pivot' \| 'table' \| 'list' \| 'text' \| 'image' \| 'frame'>` | optional | Visualization type | +| **object** | `string` | optional | Data source object name | +| **filter** | `any` | optional | Data filter criteria | +| **categoryField** | `string` | optional | Field for grouping (X-Axis) | +| **valueField** | `string` | optional | Field for values (Y-Axis) | +| **aggregate** | `Enum<'count' \| 'sum' \| 'avg' \| 'min' \| 'max'>` | optional | Aggregate function | +| **layout** | `object` | ✅ | Grid layout position | +| **options** | `any` | optional | Widget specific configuration | + diff --git a/content/docs/references/ui/dashboard/ChartType.mdx b/content/docs/references/ui/dashboard/ChartType.mdx deleted file mode 100644 index 363b133c7..000000000 --- a/content/docs/references/ui/dashboard/ChartType.mdx +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: ChartType -description: ChartType Schema Reference ---- - -## Allowed Values - -* `metric` -* `bar` -* `line` -* `pie` -* `donut` -* `gauge` -* `funnel` -* `radar` -* `scatter` -* `heatmap` -* `pivot` -* `table` -* `list` -* `text` -* `image` -* `frame` \ No newline at end of file diff --git a/content/docs/references/ui/dashboard/Dashboard.mdx b/content/docs/references/ui/dashboard/Dashboard.mdx deleted file mode 100644 index 5e042dc3b..000000000 --- a/content/docs/references/ui/dashboard/Dashboard.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Dashboard -description: Dashboard Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Dashboard unique name | -| **label** | `string` | ✅ | Dashboard label | -| **description** | `string` | optional | Dashboard description | -| **widgets** | `object[]` | ✅ | Widgets to display | diff --git a/content/docs/references/ui/dashboard/DashboardWidget.mdx b/content/docs/references/ui/dashboard/DashboardWidget.mdx deleted file mode 100644 index 0084d1ae4..000000000 --- a/content/docs/references/ui/dashboard/DashboardWidget.mdx +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: DashboardWidget -description: DashboardWidget Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **title** | `string` | optional | Widget title | -| **type** | `Enum<'metric' \| 'bar' \| 'line' \| 'pie' \| 'donut' \| 'gauge' \| 'funnel' \| 'radar' \| 'scatter' \| 'heatmap' \| 'pivot' \| 'table' \| 'list' \| 'text' \| 'image' \| 'frame'>` | optional | Visualization type | -| **object** | `string` | optional | Data source object name | -| **filter** | `any` | optional | Data filter criteria | -| **categoryField** | `string` | optional | Field for grouping (X-Axis) | -| **valueField** | `string` | optional | Field for values (Y-Axis) | -| **aggregate** | `Enum<'count' \| 'sum' \| 'avg' \| 'min' \| 'max'>` | optional | Aggregate function | -| **layout** | `object` | ✅ | Grid layout position | -| **options** | `any` | optional | Widget specific configuration | diff --git a/content/docs/references/ui/dashboard/meta.json b/content/docs/references/ui/dashboard/meta.json deleted file mode 100644 index cfc92c3ca..000000000 --- a/content/docs/references/ui/dashboard/meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "title": "Dashboard" -} \ No newline at end of file diff --git a/content/docs/references/ui/index.mdx b/content/docs/references/ui/index.mdx new file mode 100644 index 000000000..301673298 --- /dev/null +++ b/content/docs/references/ui/index.mdx @@ -0,0 +1,22 @@ +--- +title: UI Protocol Overview +description: Complete reference for all ui protocol schemas +--- + +# UI Protocol + +This section contains all protocol schemas for the ui layer of ObjectStack. + + + + + + + + + + + + + + diff --git a/content/docs/references/ui/page.mdx b/content/docs/references/ui/page.mdx new file mode 100644 index 000000000..3f31fe1b1 --- /dev/null +++ b/content/docs/references/ui/page.mdx @@ -0,0 +1,93 @@ +--- +title: Page +description: Page protocol schemas +--- + +# Page + + +**Source:** `packages/spec/src/ui/page.zod.ts` + + +## TypeScript Usage + +```typescript +import { PageSchema, PageComponentSchema, PageComponentTypeSchema, PageRegionSchema } from '@objectstack/spec/ui'; +import type { Page, PageComponent, PageComponentType, PageRegion } from '@objectstack/spec/ui'; + +// Validate data +const result = PageSchema.parse(data); +``` + +--- + +## Page + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Page unique name (lowercase snake_case) | +| **label** | `string` | ✅ | | +| **description** | `string` | optional | | +| **type** | `Enum<'record' \| 'home' \| 'app' \| 'utility'>` | optional | | +| **object** | `string` | optional | Bound object (for Record pages) | +| **template** | `string` | optional | Layout template name (e.g. "header-sidebar-main") | +| **regions** | `object[]` | ✅ | Defined regions with components | +| **isDefault** | `boolean` | optional | | +| **assignedProfiles** | `string[]` | optional | | + +--- + +## PageComponent + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **type** | `Enum<'page:header' \| 'page:footer' \| 'page:sidebar' \| 'page:tabs' \| 'page:accordion' \| 'page:card' \| 'page:section' \| 'record:details' \| 'record:highlights' \| 'record:related_list' \| 'record:activity' \| 'record:chatter' \| 'record:path' \| 'app:launcher' \| 'nav:menu' \| 'nav:breadcrumb' \| 'global:search' \| 'global:notifications' \| 'user:profile' \| 'ai:chat_window' \| 'ai:suggestion'> \| string` | ✅ | Component Type (Standard enum or custom string) | +| **id** | `string` | optional | Unique instance ID | +| **label** | `string` | optional | | +| **properties** | `Record` | ✅ | Component props passed to the widget. See block.zod.ts for schemas. | +| **visibility** | `string` | optional | Visibility filter/formula | + +--- + +## PageComponentType + +### Allowed Values + +* `page:header` +* `page:footer` +* `page:sidebar` +* `page:tabs` +* `page:accordion` +* `page:card` +* `page:section` +* `record:details` +* `record:highlights` +* `record:related_list` +* `record:activity` +* `record:chatter` +* `record:path` +* `app:launcher` +* `nav:menu` +* `nav:breadcrumb` +* `global:search` +* `global:notifications` +* `user:profile` +* `ai:chat_window` +* `ai:suggestion` + +--- + +## PageRegion + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Region name (e.g. "sidebar", "main", "header") | +| **width** | `Enum<'small' \| 'medium' \| 'large' \| 'full'>` | optional | | +| **components** | `object[]` | ✅ | Components in this region | + diff --git a/content/docs/references/ui/page/Page.mdx b/content/docs/references/ui/page/Page.mdx deleted file mode 100644 index 31b53a195..000000000 --- a/content/docs/references/ui/page/Page.mdx +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Page -description: Page Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Page unique name (lowercase snake_case) | -| **label** | `string` | ✅ | | -| **description** | `string` | optional | | -| **type** | `Enum<'record' \| 'home' \| 'app' \| 'utility'>` | optional | | -| **object** | `string` | optional | Bound object (for Record pages) | -| **template** | `string` | optional | Layout template name (e.g. "header-sidebar-main") | -| **regions** | `object[]` | ✅ | Defined regions with components | -| **isDefault** | `boolean` | optional | | -| **assignedProfiles** | `string[]` | optional | | diff --git a/content/docs/references/ui/page/PageComponent.mdx b/content/docs/references/ui/page/PageComponent.mdx deleted file mode 100644 index e6d232530..000000000 --- a/content/docs/references/ui/page/PageComponent.mdx +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: PageComponent -description: PageComponent Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `Enum<'page:header' \| 'page:footer' \| 'page:sidebar' \| 'page:tabs' \| 'page:accordion' \| 'page:card' \| 'page:section' \| 'record:details' \| 'record:highlights' \| 'record:related_list' \| 'record:activity' \| 'record:chatter' \| 'record:path' \| 'app:launcher' \| 'nav:menu' \| 'nav:breadcrumb' \| 'global:search' \| 'global:notifications' \| 'user:profile' \| 'ai:chat_window' \| 'ai:suggestion'> \| string` | ✅ | Component Type (Standard enum or custom string) | -| **id** | `string` | optional | Unique instance ID | -| **label** | `string` | optional | | -| **properties** | `Record` | ✅ | Component props passed to the widget. See block.zod.ts for schemas. | -| **visibility** | `string` | optional | Visibility filter/formula | diff --git a/content/docs/references/ui/page/PageComponentType.mdx b/content/docs/references/ui/page/PageComponentType.mdx deleted file mode 100644 index b454a22d5..000000000 --- a/content/docs/references/ui/page/PageComponentType.mdx +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: PageComponentType -description: PageComponentType Schema Reference ---- - -## Allowed Values - -* `page:header` -* `page:footer` -* `page:sidebar` -* `page:tabs` -* `page:accordion` -* `page:card` -* `page:section` -* `record:details` -* `record:highlights` -* `record:related_list` -* `record:activity` -* `record:chatter` -* `record:path` -* `app:launcher` -* `nav:menu` -* `nav:breadcrumb` -* `global:search` -* `global:notifications` -* `user:profile` -* `ai:chat_window` -* `ai:suggestion` \ No newline at end of file diff --git a/content/docs/references/ui/page/PageRegion.mdx b/content/docs/references/ui/page/PageRegion.mdx deleted file mode 100644 index 1340f51ad..000000000 --- a/content/docs/references/ui/page/PageRegion.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: PageRegion -description: PageRegion Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Region name (e.g. "sidebar", "main", "header") | -| **width** | `Enum<'small' \| 'medium' \| 'large' \| 'full'>` | optional | | -| **components** | `object[]` | ✅ | Components in this region | diff --git a/content/docs/references/ui/page/meta.json b/content/docs/references/ui/page/meta.json deleted file mode 100644 index 527041315..000000000 --- a/content/docs/references/ui/page/meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "title": "Page" -} \ No newline at end of file diff --git a/content/docs/references/ui/report.mdx b/content/docs/references/ui/report.mdx new file mode 100644 index 000000000..fdaffbbc4 --- /dev/null +++ b/content/docs/references/ui/report.mdx @@ -0,0 +1,89 @@ +--- +title: Report +description: Report protocol schemas +--- + +# Report + + +**Source:** `packages/spec/src/ui/report.zod.ts` + + +## TypeScript Usage + +```typescript +import { ReportSchema, ReportChartSchema, ReportColumnSchema, ReportGroupingSchema, ReportTypeSchema } from '@objectstack/spec/ui'; +import type { Report, ReportChart, ReportColumn, ReportGrouping, ReportType } from '@objectstack/spec/ui'; + +// Validate data +const result = ReportSchema.parse(data); +``` + +--- + +## Report + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Report unique name | +| **label** | `string` | ✅ | Report label | +| **description** | `string` | optional | | +| **objectName** | `string` | ✅ | Primary object | +| **type** | `Enum<'tabular' \| 'summary' \| 'matrix' \| 'joined'>` | optional | Report format type | +| **columns** | `object[]` | ✅ | Columns to display | +| **groupingsDown** | `object[]` | optional | Row groupings | +| **groupingsAcross** | `object[]` | optional | Column groupings (Matrix only) | +| **filter** | `any` | optional | Filter criteria | +| **chart** | `object` | optional | Embedded chart configuration | + +--- + +## ReportChart + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **type** | `Enum<'bar' \| 'column' \| 'line' \| 'pie' \| 'donut' \| 'scatter' \| 'funnel'>` | ✅ | Chart type | +| **title** | `string` | optional | | +| **showLegend** | `boolean` | optional | | +| **xAxis** | `string` | ✅ | Grouping field for X-Axis | +| **yAxis** | `string` | ✅ | Summary field for Y-Axis | + +--- + +## ReportColumn + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **field** | `string` | ✅ | Field name | +| **label** | `string` | optional | Override label | +| **aggregate** | `Enum<'sum' \| 'avg' \| 'max' \| 'min' \| 'count' \| 'unique'>` | optional | Aggregation function | + +--- + +## ReportGrouping + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **field** | `string` | ✅ | Field to group by | +| **sortOrder** | `Enum<'asc' \| 'desc'>` | optional | | +| **dateGranularity** | `Enum<'day' \| 'week' \| 'month' \| 'quarter' \| 'year'>` | optional | For date fields | + +--- + +## ReportType + +### Allowed Values + +* `tabular` +* `summary` +* `matrix` +* `joined` + diff --git a/content/docs/references/ui/report/Report.mdx b/content/docs/references/ui/report/Report.mdx deleted file mode 100644 index 68954c597..000000000 --- a/content/docs/references/ui/report/Report.mdx +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Report -description: Report Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Report unique name | -| **label** | `string` | ✅ | Report label | -| **description** | `string` | optional | | -| **objectName** | `string` | ✅ | Primary object | -| **type** | `Enum<'tabular' \| 'summary' \| 'matrix' \| 'joined'>` | optional | Report format type | -| **columns** | `object[]` | ✅ | Columns to display | -| **groupingsDown** | `object[]` | optional | Row groupings | -| **groupingsAcross** | `object[]` | optional | Column groupings (Matrix only) | -| **filter** | `any` | optional | Filter criteria | -| **chart** | `object` | optional | Embedded chart configuration | diff --git a/content/docs/references/ui/report/ReportChart.mdx b/content/docs/references/ui/report/ReportChart.mdx deleted file mode 100644 index b6c342462..000000000 --- a/content/docs/references/ui/report/ReportChart.mdx +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: ReportChart -description: ReportChart Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `Enum<'bar' \| 'column' \| 'line' \| 'pie' \| 'donut' \| 'scatter' \| 'funnel'>` | ✅ | Chart type | -| **title** | `string` | optional | | -| **showLegend** | `boolean` | optional | | -| **xAxis** | `string` | ✅ | Grouping field for X-Axis | -| **yAxis** | `string` | ✅ | Summary field for Y-Axis | diff --git a/content/docs/references/ui/report/ReportColumn.mdx b/content/docs/references/ui/report/ReportColumn.mdx deleted file mode 100644 index 607e8ace1..000000000 --- a/content/docs/references/ui/report/ReportColumn.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: ReportColumn -description: ReportColumn Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **field** | `string` | ✅ | Field name | -| **label** | `string` | optional | Override label | -| **aggregate** | `Enum<'sum' \| 'avg' \| 'max' \| 'min' \| 'count' \| 'unique'>` | optional | Aggregation function | diff --git a/content/docs/references/ui/report/ReportGrouping.mdx b/content/docs/references/ui/report/ReportGrouping.mdx deleted file mode 100644 index e82ab5ada..000000000 --- a/content/docs/references/ui/report/ReportGrouping.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: ReportGrouping -description: ReportGrouping Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **field** | `string` | ✅ | Field to group by | -| **sortOrder** | `Enum<'asc' \| 'desc'>` | optional | | -| **dateGranularity** | `Enum<'day' \| 'week' \| 'month' \| 'quarter' \| 'year'>` | optional | For date fields | diff --git a/content/docs/references/ui/report/ReportType.mdx b/content/docs/references/ui/report/ReportType.mdx deleted file mode 100644 index db2609f65..000000000 --- a/content/docs/references/ui/report/ReportType.mdx +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: ReportType -description: ReportType Schema Reference ---- - -## Allowed Values - -* `tabular` -* `summary` -* `matrix` -* `joined` \ No newline at end of file diff --git a/content/docs/references/ui/report/meta.json b/content/docs/references/ui/report/meta.json deleted file mode 100644 index 09ce8c366..000000000 --- a/content/docs/references/ui/report/meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "title": "Report" -} \ No newline at end of file diff --git a/content/docs/references/ui/theme.mdx b/content/docs/references/ui/theme.mdx new file mode 100644 index 000000000..451f790ab --- /dev/null +++ b/content/docs/references/ui/theme.mdx @@ -0,0 +1,194 @@ +--- +title: Theme +description: Theme protocol schemas +--- + +# Theme + + +**Source:** `packages/spec/src/ui/theme.zod.ts` + + +## TypeScript Usage + +```typescript +import { AnimationSchema, BorderRadiusSchema, BreakpointsSchema, ColorPaletteSchema, ShadowSchema, SpacingSchema, ThemeSchema, ThemeModeSchema, TypographySchema, ZIndexSchema } from '@objectstack/spec/ui'; +import type { Animation, BorderRadius, Breakpoints, ColorPalette, Shadow, Spacing, Theme, ThemeMode, Typography, ZIndex } from '@objectstack/spec/ui'; + +// Validate data +const result = AnimationSchema.parse(data); +``` + +--- + +## Animation + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **duration** | `object` | optional | | +| **timing** | `object` | optional | | + +--- + +## BorderRadius + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **none** | `string` | optional | No border radius (0) | +| **sm** | `string` | optional | Small border radius (e.g., 0.125rem) | +| **base** | `string` | optional | Base border radius (e.g., 0.25rem) | +| **md** | `string` | optional | Medium border radius (e.g., 0.375rem) | +| **lg** | `string` | optional | Large border radius (e.g., 0.5rem) | +| **xl** | `string` | optional | Extra large border radius (e.g., 0.75rem) | +| **2xl** | `string` | optional | 2X large border radius (e.g., 1rem) | +| **full** | `string` | optional | Full border radius (50%) | + +--- + +## Breakpoints + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **xs** | `string` | optional | Extra small breakpoint (e.g., 480px) | +| **sm** | `string` | optional | Small breakpoint (e.g., 640px) | +| **md** | `string` | optional | Medium breakpoint (e.g., 768px) | +| **lg** | `string` | optional | Large breakpoint (e.g., 1024px) | +| **xl** | `string` | optional | Extra large breakpoint (e.g., 1280px) | +| **2xl** | `string` | optional | 2X large breakpoint (e.g., 1536px) | + +--- + +## ColorPalette + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **primary** | `string` | ✅ | Primary brand color (hex, rgb, or hsl) | +| **secondary** | `string` | optional | Secondary brand color | +| **accent** | `string` | optional | Accent color for highlights | +| **success** | `string` | optional | Success state color (default: green) | +| **warning** | `string` | optional | Warning state color (default: yellow) | +| **error** | `string` | optional | Error state color (default: red) | +| **info** | `string` | optional | Info state color (default: blue) | +| **background** | `string` | optional | Background color | +| **surface** | `string` | optional | Surface/card background color | +| **text** | `string` | optional | Primary text color | +| **textSecondary** | `string` | optional | Secondary text color | +| **border** | `string` | optional | Border color | +| **disabled** | `string` | optional | Disabled state color | +| **primaryLight** | `string` | optional | Lighter shade of primary | +| **primaryDark** | `string` | optional | Darker shade of primary | +| **secondaryLight** | `string` | optional | Lighter shade of secondary | +| **secondaryDark** | `string` | optional | Darker shade of secondary | + +--- + +## Shadow + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **none** | `string` | optional | No shadow | +| **sm** | `string` | optional | Small shadow | +| **base** | `string` | optional | Base shadow | +| **md** | `string` | optional | Medium shadow | +| **lg** | `string` | optional | Large shadow | +| **xl** | `string` | optional | Extra large shadow | +| **2xl** | `string` | optional | 2X large shadow | +| **inner** | `string` | optional | Inner shadow (inset) | + +--- + +## Spacing + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **0** | `string` | optional | 0 spacing (0) | +| **1** | `string` | optional | Spacing unit 1 (e.g., 0.25rem) | +| **2** | `string` | optional | Spacing unit 2 (e.g., 0.5rem) | +| **3** | `string` | optional | Spacing unit 3 (e.g., 0.75rem) | +| **4** | `string` | optional | Spacing unit 4 (e.g., 1rem) | +| **5** | `string` | optional | Spacing unit 5 (e.g., 1.25rem) | +| **6** | `string` | optional | Spacing unit 6 (e.g., 1.5rem) | +| **8** | `string` | optional | Spacing unit 8 (e.g., 2rem) | +| **10** | `string` | optional | Spacing unit 10 (e.g., 2.5rem) | +| **12** | `string` | optional | Spacing unit 12 (e.g., 3rem) | +| **16** | `string` | optional | Spacing unit 16 (e.g., 4rem) | +| **20** | `string` | optional | Spacing unit 20 (e.g., 5rem) | +| **24** | `string` | optional | Spacing unit 24 (e.g., 6rem) | + +--- + +## Theme + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Unique theme identifier (snake_case) | +| **label** | `string` | ✅ | Human-readable theme name | +| **description** | `string` | optional | Theme description | +| **mode** | `Enum<'light' \| 'dark' \| 'auto'>` | optional | Theme mode (light, dark, or auto) | +| **colors** | `object` | ✅ | Color palette configuration | +| **typography** | `object` | optional | Typography settings | +| **spacing** | `object` | optional | Spacing scale | +| **borderRadius** | `object` | optional | Border radius scale | +| **shadows** | `object` | optional | Box shadow effects | +| **breakpoints** | `object` | optional | Responsive breakpoints | +| **animation** | `object` | optional | Animation settings | +| **zIndex** | `object` | optional | Z-index scale for layering | +| **customVars** | `Record` | optional | Custom CSS variables (key-value pairs) | +| **logo** | `object` | optional | Logo assets | +| **extends** | `string` | optional | Base theme to extend from | + +--- + +## ThemeMode + +### Allowed Values + +* `light` +* `dark` +* `auto` + +--- + +## Typography + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **fontFamily** | `object` | optional | | +| **fontSize** | `object` | optional | | +| **fontWeight** | `object` | optional | | +| **lineHeight** | `object` | optional | | +| **letterSpacing** | `object` | optional | | + +--- + +## ZIndex + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **base** | `number` | optional | Base z-index (e.g., 0) | +| **dropdown** | `number` | optional | Dropdown z-index (e.g., 1000) | +| **sticky** | `number` | optional | Sticky z-index (e.g., 1020) | +| **fixed** | `number` | optional | Fixed z-index (e.g., 1030) | +| **modalBackdrop** | `number` | optional | Modal backdrop z-index (e.g., 1040) | +| **modal** | `number` | optional | Modal z-index (e.g., 1050) | +| **popover** | `number` | optional | Popover z-index (e.g., 1060) | +| **tooltip** | `number` | optional | Tooltip z-index (e.g., 1070) | + diff --git a/content/docs/references/ui/theme/Animation.mdx b/content/docs/references/ui/theme/Animation.mdx deleted file mode 100644 index ff48ac9ba..000000000 --- a/content/docs/references/ui/theme/Animation.mdx +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Animation -description: Animation Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **duration** | `object` | optional | | -| **timing** | `object` | optional | | diff --git a/content/docs/references/ui/theme/BorderRadius.mdx b/content/docs/references/ui/theme/BorderRadius.mdx deleted file mode 100644 index e4a7dc165..000000000 --- a/content/docs/references/ui/theme/BorderRadius.mdx +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: BorderRadius -description: BorderRadius Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **none** | `string` | optional | No border radius (0) | -| **sm** | `string` | optional | Small border radius (e.g., 0.125rem) | -| **base** | `string` | optional | Base border radius (e.g., 0.25rem) | -| **md** | `string` | optional | Medium border radius (e.g., 0.375rem) | -| **lg** | `string` | optional | Large border radius (e.g., 0.5rem) | -| **xl** | `string` | optional | Extra large border radius (e.g., 0.75rem) | -| **2xl** | `string` | optional | 2X large border radius (e.g., 1rem) | -| **full** | `string` | optional | Full border radius (50%) | diff --git a/content/docs/references/ui/theme/Breakpoints.mdx b/content/docs/references/ui/theme/Breakpoints.mdx deleted file mode 100644 index bdbaeed87..000000000 --- a/content/docs/references/ui/theme/Breakpoints.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: Breakpoints -description: Breakpoints Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **xs** | `string` | optional | Extra small breakpoint (e.g., 480px) | -| **sm** | `string` | optional | Small breakpoint (e.g., 640px) | -| **md** | `string` | optional | Medium breakpoint (e.g., 768px) | -| **lg** | `string` | optional | Large breakpoint (e.g., 1024px) | -| **xl** | `string` | optional | Extra large breakpoint (e.g., 1280px) | -| **2xl** | `string` | optional | 2X large breakpoint (e.g., 1536px) | diff --git a/content/docs/references/ui/theme/ColorPalette.mdx b/content/docs/references/ui/theme/ColorPalette.mdx deleted file mode 100644 index 346dd8fe4..000000000 --- a/content/docs/references/ui/theme/ColorPalette.mdx +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: ColorPalette -description: ColorPalette Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **primary** | `string` | ✅ | Primary brand color (hex, rgb, or hsl) | -| **secondary** | `string` | optional | Secondary brand color | -| **accent** | `string` | optional | Accent color for highlights | -| **success** | `string` | optional | Success state color (default: green) | -| **warning** | `string` | optional | Warning state color (default: yellow) | -| **error** | `string` | optional | Error state color (default: red) | -| **info** | `string` | optional | Info state color (default: blue) | -| **background** | `string` | optional | Background color | -| **surface** | `string` | optional | Surface/card background color | -| **text** | `string` | optional | Primary text color | -| **textSecondary** | `string` | optional | Secondary text color | -| **border** | `string` | optional | Border color | -| **disabled** | `string` | optional | Disabled state color | -| **primaryLight** | `string` | optional | Lighter shade of primary | -| **primaryDark** | `string` | optional | Darker shade of primary | -| **secondaryLight** | `string` | optional | Lighter shade of secondary | -| **secondaryDark** | `string` | optional | Darker shade of secondary | diff --git a/content/docs/references/ui/theme/Shadow.mdx b/content/docs/references/ui/theme/Shadow.mdx deleted file mode 100644 index 4fe3c269f..000000000 --- a/content/docs/references/ui/theme/Shadow.mdx +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: Shadow -description: Shadow Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **none** | `string` | optional | No shadow | -| **sm** | `string` | optional | Small shadow | -| **base** | `string` | optional | Base shadow | -| **md** | `string` | optional | Medium shadow | -| **lg** | `string` | optional | Large shadow | -| **xl** | `string` | optional | Extra large shadow | -| **2xl** | `string` | optional | 2X large shadow | -| **inner** | `string` | optional | Inner shadow (inset) | diff --git a/content/docs/references/ui/theme/Spacing.mdx b/content/docs/references/ui/theme/Spacing.mdx deleted file mode 100644 index 127bb81f1..000000000 --- a/content/docs/references/ui/theme/Spacing.mdx +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: Spacing -description: Spacing Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **0** | `string` | optional | 0 spacing (0) | -| **1** | `string` | optional | Spacing unit 1 (e.g., 0.25rem) | -| **2** | `string` | optional | Spacing unit 2 (e.g., 0.5rem) | -| **3** | `string` | optional | Spacing unit 3 (e.g., 0.75rem) | -| **4** | `string` | optional | Spacing unit 4 (e.g., 1rem) | -| **5** | `string` | optional | Spacing unit 5 (e.g., 1.25rem) | -| **6** | `string` | optional | Spacing unit 6 (e.g., 1.5rem) | -| **8** | `string` | optional | Spacing unit 8 (e.g., 2rem) | -| **10** | `string` | optional | Spacing unit 10 (e.g., 2.5rem) | -| **12** | `string` | optional | Spacing unit 12 (e.g., 3rem) | -| **16** | `string` | optional | Spacing unit 16 (e.g., 4rem) | -| **20** | `string` | optional | Spacing unit 20 (e.g., 5rem) | -| **24** | `string` | optional | Spacing unit 24 (e.g., 6rem) | diff --git a/content/docs/references/ui/theme/Theme.mdx b/content/docs/references/ui/theme/Theme.mdx deleted file mode 100644 index e1131ecb1..000000000 --- a/content/docs/references/ui/theme/Theme.mdx +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Theme -description: Theme Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Unique theme identifier (snake_case) | -| **label** | `string` | ✅ | Human-readable theme name | -| **description** | `string` | optional | Theme description | -| **mode** | `Enum<'light' \| 'dark' \| 'auto'>` | optional | Theme mode (light, dark, or auto) | -| **colors** | `object` | ✅ | Color palette configuration | -| **typography** | `object` | optional | Typography settings | -| **spacing** | `object` | optional | Spacing scale | -| **borderRadius** | `object` | optional | Border radius scale | -| **shadows** | `object` | optional | Box shadow effects | -| **breakpoints** | `object` | optional | Responsive breakpoints | -| **animation** | `object` | optional | Animation settings | -| **zIndex** | `object` | optional | Z-index scale for layering | -| **customVars** | `Record` | optional | Custom CSS variables (key-value pairs) | -| **logo** | `object` | optional | Logo assets | -| **extends** | `string` | optional | Base theme to extend from | diff --git a/content/docs/references/ui/theme/ThemeMode.mdx b/content/docs/references/ui/theme/ThemeMode.mdx deleted file mode 100644 index 553ecaeb7..000000000 --- a/content/docs/references/ui/theme/ThemeMode.mdx +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: ThemeMode -description: ThemeMode Schema Reference ---- - -## Allowed Values - -* `light` -* `dark` -* `auto` \ No newline at end of file diff --git a/content/docs/references/ui/theme/Typography.mdx b/content/docs/references/ui/theme/Typography.mdx deleted file mode 100644 index e04d15c48..000000000 --- a/content/docs/references/ui/theme/Typography.mdx +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: Typography -description: Typography Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **fontFamily** | `object` | optional | | -| **fontSize** | `object` | optional | | -| **fontWeight** | `object` | optional | | -| **lineHeight** | `object` | optional | | -| **letterSpacing** | `object` | optional | | diff --git a/content/docs/references/ui/theme/ZIndex.mdx b/content/docs/references/ui/theme/ZIndex.mdx deleted file mode 100644 index 1e570762c..000000000 --- a/content/docs/references/ui/theme/ZIndex.mdx +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: ZIndex -description: ZIndex Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **base** | `number` | optional | Base z-index (e.g., 0) | -| **dropdown** | `number` | optional | Dropdown z-index (e.g., 1000) | -| **sticky** | `number` | optional | Sticky z-index (e.g., 1020) | -| **fixed** | `number` | optional | Fixed z-index (e.g., 1030) | -| **modalBackdrop** | `number` | optional | Modal backdrop z-index (e.g., 1040) | -| **modal** | `number` | optional | Modal z-index (e.g., 1050) | -| **popover** | `number` | optional | Popover z-index (e.g., 1060) | -| **tooltip** | `number` | optional | Tooltip z-index (e.g., 1070) | diff --git a/content/docs/references/ui/theme/meta.json b/content/docs/references/ui/theme/meta.json deleted file mode 100644 index 23efbd7e3..000000000 --- a/content/docs/references/ui/theme/meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "title": "Theme" -} \ No newline at end of file diff --git a/content/docs/references/ui/view.mdx b/content/docs/references/ui/view.mdx new file mode 100644 index 000000000..5c7b8ca23 --- /dev/null +++ b/content/docs/references/ui/view.mdx @@ -0,0 +1,214 @@ +--- +title: View +description: View protocol schemas +--- + +# View + + +**Source:** `packages/spec/src/ui/view.zod.ts` + + +## TypeScript Usage + +```typescript +import { CalendarConfigSchema, FormFieldSchema, FormSectionSchema, FormViewSchema, GanttConfigSchema, HttpMethodSchema, HttpRequestSchema, KanbanConfigSchema, ListColumnSchema, ListViewSchema, PaginationConfigSchema, SelectionConfigSchema, ViewSchema, ViewDataSchema } from '@objectstack/spec/ui'; +import type { CalendarConfig, FormField, FormSection, FormView, GanttConfig, HttpMethod, HttpRequest, KanbanConfig, ListColumn, ListView, PaginationConfig, SelectionConfig, View, ViewData } from '@objectstack/spec/ui'; + +// Validate data +const result = CalendarConfigSchema.parse(data); +``` + +--- + +## CalendarConfig + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **startDateField** | `string` | ✅ | | +| **endDateField** | `string` | optional | | +| **titleField** | `string` | ✅ | | +| **colorField** | `string` | optional | | + +--- + +## FormField + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **field** | `string` | ✅ | Field name (snake_case) | +| **label** | `string` | optional | Display label override | +| **placeholder** | `string` | optional | Placeholder text | +| **helpText** | `string` | optional | Help/hint text | +| **readonly** | `boolean` | optional | Read-only override | +| **required** | `boolean` | optional | Required override | +| **hidden** | `boolean` | optional | Hidden override | +| **colSpan** | `integer` | optional | Column span in grid layout (1-4) | +| **widget** | `string` | optional | Custom widget/component name | +| **dependsOn** | `string` | optional | Parent field name for cascading | +| **visibleOn** | `string` | optional | Visibility condition expression | + +--- + +## FormSection + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **label** | `string` | optional | | +| **collapsible** | `boolean` | optional | | +| **collapsed** | `boolean` | optional | | +| **columns** | `Enum<'1' \| '2' \| '3' \| '4'>` | optional | | +| **fields** | `string \| object[]` | ✅ | | + +--- + +## FormView + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **type** | `Enum<'simple' \| 'tabbed' \| 'wizard' \| 'split' \| 'drawer' \| 'modal'>` | optional | | +| **data** | `object \| object \| object` | optional | Data source configuration (defaults to "object" provider) | +| **sections** | `object[]` | optional | | +| **groups** | `object[]` | optional | | + +--- + +## GanttConfig + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **startDateField** | `string` | ✅ | | +| **endDateField** | `string` | ✅ | | +| **titleField** | `string` | ✅ | | +| **progressField** | `string` | optional | | +| **dependenciesField** | `string` | optional | | + +--- + +## HttpMethod + +### Allowed Values + +* `GET` +* `POST` +* `PUT` +* `PATCH` +* `DELETE` + +--- + +## HttpRequest + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **url** | `string` | ✅ | API endpoint URL | +| **method** | `Enum<'GET' \| 'POST' \| 'PUT' \| 'PATCH' \| 'DELETE'>` | optional | HTTP method | +| **headers** | `Record` | optional | Custom HTTP headers | +| **params** | `Record` | optional | Query parameters | +| **body** | `any` | optional | Request body for POST/PUT/PATCH | + +--- + +## KanbanConfig + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **groupByField** | `string` | ✅ | Field to group columns by (usually status/select) | +| **summarizeField** | `string` | optional | Field to sum at top of column (e.g. amount) | +| **columns** | `string[]` | ✅ | Fields to show on cards | + +--- + +## ListColumn + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **field** | `string` | ✅ | Field name (snake_case) | +| **label** | `string` | optional | Display label override | +| **width** | `number` | optional | Column width in pixels | +| **align** | `Enum<'left' \| 'center' \| 'right'>` | optional | Text alignment | +| **hidden** | `boolean` | optional | Hide column by default | +| **sortable** | `boolean` | optional | Allow sorting by this column | +| **resizable** | `boolean` | optional | Allow resizing this column | +| **wrap** | `boolean` | optional | Allow text wrapping | +| **type** | `string` | optional | Renderer type override (e.g., "currency", "date") | + +--- + +## ListView + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | optional | Internal view name (lowercase snake_case) | +| **label** | `string` | optional | | +| **type** | `Enum<'grid' \| 'spreadsheet' \| 'kanban' \| 'gallery' \| 'calendar' \| 'timeline' \| 'gantt' \| 'map'>` | optional | | +| **data** | `object \| object \| object` | optional | Data source configuration (defaults to "object" provider) | +| **columns** | `string[] \| object[]` | ✅ | Fields to display as columns | +| **filter** | `any[]` | optional | Filter criteria (JSON Rules) | +| **sort** | `string \| object[]` | optional | | +| **searchableFields** | `string[]` | optional | Fields enabled for search | +| **resizable** | `boolean` | optional | Enable column resizing | +| **striped** | `boolean` | optional | Striped row styling | +| **bordered** | `boolean` | optional | Show borders | +| **selection** | `object` | optional | Row selection configuration | +| **pagination** | `object` | optional | Pagination configuration | +| **kanban** | `object` | optional | | +| **calendar** | `object` | optional | | +| **gantt** | `object` | optional | | + +--- + +## PaginationConfig + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **pageSize** | `integer` | optional | Number of records per page | +| **pageSizeOptions** | `integer[]` | optional | Available page size options | + +--- + +## SelectionConfig + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **type** | `Enum<'none' \| 'single' \| 'multiple'>` | optional | Selection mode | + +--- + +## View + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **list** | `object` | optional | | +| **form** | `object` | optional | | +| **listViews** | `Record` | optional | Additional named list views | +| **formViews** | `Record` | optional | Additional named form views | + +--- + +## ViewData + diff --git a/content/docs/references/ui/view/CalendarConfig.mdx b/content/docs/references/ui/view/CalendarConfig.mdx deleted file mode 100644 index b47adbfa2..000000000 --- a/content/docs/references/ui/view/CalendarConfig.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: CalendarConfig -description: CalendarConfig Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **startDateField** | `string` | ✅ | | -| **endDateField** | `string` | optional | | -| **titleField** | `string` | ✅ | | -| **colorField** | `string` | optional | | diff --git a/content/docs/references/ui/view/FormField.mdx b/content/docs/references/ui/view/FormField.mdx deleted file mode 100644 index e0e56aa1c..000000000 --- a/content/docs/references/ui/view/FormField.mdx +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: FormField -description: FormField Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **field** | `string` | ✅ | Field name (snake_case) | -| **label** | `string` | optional | Display label override | -| **placeholder** | `string` | optional | Placeholder text | -| **helpText** | `string` | optional | Help/hint text | -| **readonly** | `boolean` | optional | Read-only override | -| **required** | `boolean` | optional | Required override | -| **hidden** | `boolean` | optional | Hidden override | -| **colSpan** | `integer` | optional | Column span in grid layout (1-4) | -| **widget** | `string` | optional | Custom widget/component name | -| **dependsOn** | `string` | optional | Parent field name for cascading | -| **visibleOn** | `string` | optional | Visibility condition expression | diff --git a/content/docs/references/ui/view/FormSection.mdx b/content/docs/references/ui/view/FormSection.mdx deleted file mode 100644 index a5c8e68e4..000000000 --- a/content/docs/references/ui/view/FormSection.mdx +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: FormSection -description: FormSection Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **label** | `string` | optional | | -| **collapsible** | `boolean` | optional | | -| **collapsed** | `boolean` | optional | | -| **columns** | `Enum<'1' \| '2' \| '3' \| '4'>` | optional | | -| **fields** | `string \| object[]` | ✅ | | diff --git a/content/docs/references/ui/view/FormView.mdx b/content/docs/references/ui/view/FormView.mdx deleted file mode 100644 index 256fe0782..000000000 --- a/content/docs/references/ui/view/FormView.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: FormView -description: FormView Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `Enum<'simple' \| 'tabbed' \| 'wizard' \| 'split' \| 'drawer' \| 'modal'>` | optional | | -| **data** | `object \| object \| object` | optional | Data source configuration (defaults to "object" provider) | -| **sections** | `object[]` | optional | | -| **groups** | `object[]` | optional | | diff --git a/content/docs/references/ui/view/GanttConfig.mdx b/content/docs/references/ui/view/GanttConfig.mdx deleted file mode 100644 index 363692d57..000000000 --- a/content/docs/references/ui/view/GanttConfig.mdx +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: GanttConfig -description: GanttConfig Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **startDateField** | `string` | ✅ | | -| **endDateField** | `string` | ✅ | | -| **titleField** | `string` | ✅ | | -| **progressField** | `string` | optional | | -| **dependenciesField** | `string` | optional | | diff --git a/content/docs/references/ui/view/HttpMethod.mdx b/content/docs/references/ui/view/HttpMethod.mdx deleted file mode 100644 index 6373632f5..000000000 --- a/content/docs/references/ui/view/HttpMethod.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: HttpMethod -description: HttpMethod Schema Reference ---- - -## Allowed Values - -* `GET` -* `POST` -* `PUT` -* `PATCH` -* `DELETE` \ No newline at end of file diff --git a/content/docs/references/ui/view/HttpRequest.mdx b/content/docs/references/ui/view/HttpRequest.mdx deleted file mode 100644 index 9e7e931dc..000000000 --- a/content/docs/references/ui/view/HttpRequest.mdx +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: HttpRequest -description: HttpRequest Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **url** | `string` | ✅ | API endpoint URL | -| **method** | `Enum<'GET' \| 'POST' \| 'PUT' \| 'PATCH' \| 'DELETE'>` | optional | HTTP method | -| **headers** | `Record` | optional | Custom HTTP headers | -| **params** | `Record` | optional | Query parameters | -| **body** | `any` | optional | Request body for POST/PUT/PATCH | diff --git a/content/docs/references/ui/view/KanbanConfig.mdx b/content/docs/references/ui/view/KanbanConfig.mdx deleted file mode 100644 index b1c12639b..000000000 --- a/content/docs/references/ui/view/KanbanConfig.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: KanbanConfig -description: KanbanConfig Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **groupByField** | `string` | ✅ | Field to group columns by (usually status/select) | -| **summarizeField** | `string` | optional | Field to sum at top of column (e.g. amount) | -| **columns** | `string[]` | ✅ | Fields to show on cards | diff --git a/content/docs/references/ui/view/ListColumn.mdx b/content/docs/references/ui/view/ListColumn.mdx deleted file mode 100644 index a9578a61b..000000000 --- a/content/docs/references/ui/view/ListColumn.mdx +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: ListColumn -description: ListColumn Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **field** | `string` | ✅ | Field name (snake_case) | -| **label** | `string` | optional | Display label override | -| **width** | `number` | optional | Column width in pixels | -| **align** | `Enum<'left' \| 'center' \| 'right'>` | optional | Text alignment | -| **hidden** | `boolean` | optional | Hide column by default | -| **sortable** | `boolean` | optional | Allow sorting by this column | -| **resizable** | `boolean` | optional | Allow resizing this column | -| **wrap** | `boolean` | optional | Allow text wrapping | -| **type** | `string` | optional | Renderer type override (e.g., "currency", "date") | diff --git a/content/docs/references/ui/view/ListView.mdx b/content/docs/references/ui/view/ListView.mdx deleted file mode 100644 index fd910c175..000000000 --- a/content/docs/references/ui/view/ListView.mdx +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: ListView -description: ListView Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | optional | Internal view name (lowercase snake_case) | -| **label** | `string` | optional | | -| **type** | `Enum<'grid' \| 'spreadsheet' \| 'kanban' \| 'gallery' \| 'calendar' \| 'timeline' \| 'gantt' \| 'map'>` | optional | | -| **data** | `object \| object \| object` | optional | Data source configuration (defaults to "object" provider) | -| **columns** | `string[] \| object[]` | ✅ | Fields to display as columns | -| **filter** | `any[]` | optional | Filter criteria (JSON Rules) | -| **sort** | `string \| object[]` | optional | | -| **searchableFields** | `string[]` | optional | Fields enabled for search | -| **resizable** | `boolean` | optional | Enable column resizing | -| **striped** | `boolean` | optional | Striped row styling | -| **bordered** | `boolean` | optional | Show borders | -| **selection** | `object` | optional | Row selection configuration | -| **pagination** | `object` | optional | Pagination configuration | -| **kanban** | `object` | optional | | -| **calendar** | `object` | optional | | -| **gantt** | `object` | optional | | diff --git a/content/docs/references/ui/view/PaginationConfig.mdx b/content/docs/references/ui/view/PaginationConfig.mdx deleted file mode 100644 index 887a7f44b..000000000 --- a/content/docs/references/ui/view/PaginationConfig.mdx +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: PaginationConfig -description: PaginationConfig Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **pageSize** | `integer` | optional | Number of records per page | -| **pageSizeOptions** | `integer[]` | optional | Available page size options | diff --git a/content/docs/references/ui/view/SelectionConfig.mdx b/content/docs/references/ui/view/SelectionConfig.mdx deleted file mode 100644 index cd7aa6348..000000000 --- a/content/docs/references/ui/view/SelectionConfig.mdx +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: SelectionConfig -description: SelectionConfig Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `Enum<'none' \| 'single' \| 'multiple'>` | optional | Selection mode | diff --git a/content/docs/references/ui/view/View.mdx b/content/docs/references/ui/view/View.mdx deleted file mode 100644 index 61dd3b7ad..000000000 --- a/content/docs/references/ui/view/View.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: View -description: View Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **list** | `object` | optional | | -| **form** | `object` | optional | | -| **listViews** | `Record` | optional | Additional named list views | -| **formViews** | `Record` | optional | Additional named form views | diff --git a/content/docs/references/ui/view/ViewData.mdx b/content/docs/references/ui/view/ViewData.mdx deleted file mode 100644 index 297acad9a..000000000 --- a/content/docs/references/ui/view/ViewData.mdx +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: ViewData -description: ViewData Schema Reference ---- - diff --git a/content/docs/references/ui/view/meta.json b/content/docs/references/ui/view/meta.json deleted file mode 100644 index efcfa4d25..000000000 --- a/content/docs/references/ui/view/meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "title": "View" -} \ No newline at end of file diff --git a/content/docs/references/ui/widget.mdx b/content/docs/references/ui/widget.mdx new file mode 100644 index 000000000..912693ec1 --- /dev/null +++ b/content/docs/references/ui/widget.mdx @@ -0,0 +1,111 @@ +--- +title: Widget +description: Widget protocol schemas +--- + +# Widget + + +**Source:** `packages/spec/src/ui/widget.zod.ts` + + +## TypeScript Usage + +```typescript +import { FieldWidgetPropsSchema, WidgetEventSchema, WidgetLifecycleSchema, WidgetManifestSchema, WidgetPropertySchema } from '@objectstack/spec/ui'; +import type { FieldWidgetProps, WidgetEvent, WidgetLifecycle, WidgetManifest, WidgetProperty } from '@objectstack/spec/ui'; + +// Validate data +const result = FieldWidgetPropsSchema.parse(data); +``` + +--- + +## FieldWidgetProps + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **value** | `any` | optional | Current field value | +| **readonly** | `boolean` | optional | Read-only mode flag | +| **required** | `boolean` | optional | Required field flag | +| **error** | `string` | optional | Validation error message | +| **field** | `object` | ✅ | Field schema definition | +| **record** | `Record` | optional | Complete record data | +| **options** | `Record` | optional | Custom widget options | + +--- + +## WidgetEvent + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Event name | +| **label** | `string` | optional | Human-readable event label | +| **description** | `string` | optional | Event description and usage | +| **bubbles** | `boolean` | optional | Whether event bubbles | +| **cancelable** | `boolean` | optional | Whether event is cancelable | +| **payload** | `Record` | optional | Event payload schema | + +--- + +## WidgetLifecycle + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **onMount** | `string` | optional | Initialization code when widget mounts | +| **onUpdate** | `string` | optional | Code to run when props change | +| **onUnmount** | `string` | optional | Cleanup code when widget unmounts | +| **onValidate** | `string` | optional | Custom validation logic | +| **onFocus** | `string` | optional | Code to run on focus | +| **onBlur** | `string` | optional | Code to run on blur | +| **onError** | `string` | optional | Error handling code | + +--- + +## WidgetManifest + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Widget identifier (snake_case) | +| **label** | `string` | ✅ | Widget display name | +| **description** | `string` | optional | Widget description | +| **version** | `string` | optional | Widget version (semver) | +| **author** | `string` | optional | Widget author | +| **icon** | `string` | optional | Widget icon | +| **fieldTypes** | `string[]` | optional | Supported field types | +| **category** | `Enum<'input' \| 'display' \| 'picker' \| 'editor' \| 'custom'>` | optional | Widget category | +| **lifecycle** | `object` | optional | Lifecycle hooks | +| **events** | `object[]` | optional | Custom events | +| **properties** | `object[]` | optional | Configuration properties | +| **implementation** | `object` | optional | Widget implementation | +| **dependencies** | `object[]` | optional | Widget dependencies | +| **screenshots** | `string[]` | optional | Screenshot URLs | +| **documentation** | `string` | optional | Documentation URL | +| **license** | `string` | optional | License (SPDX identifier) | +| **tags** | `string[]` | optional | Tags for categorization | + +--- + +## WidgetProperty + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Property name (camelCase) | +| **label** | `string` | optional | Human-readable label | +| **type** | `Enum<'string' \| 'number' \| 'boolean' \| 'array' \| 'object' \| 'function' \| 'any'>` | ✅ | TypeScript type | +| **required** | `boolean` | optional | Whether property is required | +| **default** | `any` | optional | Default value | +| **description** | `string` | optional | Property description | +| **validation** | `Record` | optional | Validation rules | +| **category** | `string` | optional | Property category | + diff --git a/content/docs/references/ui/widget/FieldWidgetProps.mdx b/content/docs/references/ui/widget/FieldWidgetProps.mdx deleted file mode 100644 index 3ff8a96d6..000000000 --- a/content/docs/references/ui/widget/FieldWidgetProps.mdx +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: FieldWidgetProps -description: FieldWidgetProps Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **value** | `any` | optional | Current field value | -| **readonly** | `boolean` | optional | Read-only mode flag | -| **required** | `boolean` | optional | Required field flag | -| **error** | `string` | optional | Validation error message | -| **field** | `object` | ✅ | Field schema definition | -| **record** | `Record` | optional | Complete record data | -| **options** | `Record` | optional | Custom widget options | diff --git a/content/docs/references/ui/widget/WidgetEvent.mdx b/content/docs/references/ui/widget/WidgetEvent.mdx deleted file mode 100644 index 223aee6ba..000000000 --- a/content/docs/references/ui/widget/WidgetEvent.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: WidgetEvent -description: WidgetEvent Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Event name | -| **label** | `string` | optional | Human-readable event label | -| **description** | `string` | optional | Event description and usage | -| **bubbles** | `boolean` | optional | Whether event bubbles | -| **cancelable** | `boolean` | optional | Whether event is cancelable | -| **payload** | `Record` | optional | Event payload schema | diff --git a/content/docs/references/ui/widget/WidgetLifecycle.mdx b/content/docs/references/ui/widget/WidgetLifecycle.mdx deleted file mode 100644 index f403efa40..000000000 --- a/content/docs/references/ui/widget/WidgetLifecycle.mdx +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: WidgetLifecycle -description: WidgetLifecycle Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **onMount** | `string` | optional | Initialization code when widget mounts | -| **onUpdate** | `string` | optional | Code to run when props change | -| **onUnmount** | `string` | optional | Cleanup code when widget unmounts | -| **onValidate** | `string` | optional | Custom validation logic | -| **onFocus** | `string` | optional | Code to run on focus | -| **onBlur** | `string` | optional | Code to run on blur | -| **onError** | `string` | optional | Error handling code | diff --git a/content/docs/references/ui/widget/WidgetManifest.mdx b/content/docs/references/ui/widget/WidgetManifest.mdx deleted file mode 100644 index 3adbf5a67..000000000 --- a/content/docs/references/ui/widget/WidgetManifest.mdx +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: WidgetManifest -description: WidgetManifest Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Widget identifier (snake_case) | -| **label** | `string` | ✅ | Widget display name | -| **description** | `string` | optional | Widget description | -| **version** | `string` | optional | Widget version (semver) | -| **author** | `string` | optional | Widget author | -| **icon** | `string` | optional | Widget icon | -| **fieldTypes** | `string[]` | optional | Supported field types | -| **category** | `Enum<'input' \| 'display' \| 'picker' \| 'editor' \| 'custom'>` | optional | Widget category | -| **lifecycle** | `object` | optional | Lifecycle hooks | -| **events** | `object[]` | optional | Custom events | -| **properties** | `object[]` | optional | Configuration properties | -| **implementation** | `object` | optional | Widget implementation | -| **dependencies** | `object[]` | optional | Widget dependencies | -| **screenshots** | `string[]` | optional | Screenshot URLs | -| **documentation** | `string` | optional | Documentation URL | -| **license** | `string` | optional | License (SPDX identifier) | -| **tags** | `string[]` | optional | Tags for categorization | diff --git a/content/docs/references/ui/widget/WidgetProperty.mdx b/content/docs/references/ui/widget/WidgetProperty.mdx deleted file mode 100644 index 5491179ba..000000000 --- a/content/docs/references/ui/widget/WidgetProperty.mdx +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: WidgetProperty -description: WidgetProperty Schema Reference ---- - -## Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Property name (camelCase) | -| **label** | `string` | optional | Human-readable label | -| **type** | `Enum<'string' \| 'number' \| 'boolean' \| 'array' \| 'object' \| 'function' \| 'any'>` | ✅ | TypeScript type | -| **required** | `boolean` | optional | Whether property is required | -| **default** | `any` | optional | Default value | -| **description** | `string` | optional | Property description | -| **validation** | `Record` | optional | Validation rules | -| **category** | `string` | optional | Property category | diff --git a/content/docs/references/ui/widget/meta.json b/content/docs/references/ui/widget/meta.json deleted file mode 100644 index cbf2edecb..000000000 --- a/content/docs/references/ui/widget/meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "title": "Widget" -} \ No newline at end of file diff --git a/packages/spec/scripts/build-docs.ts b/packages/spec/scripts/build-docs.ts index 68f31ea19..32b485e3d 100644 --- a/packages/spec/scripts/build-docs.ts +++ b/packages/spec/scripts/build-docs.ts @@ -90,20 +90,24 @@ function formatType(prop: any): string { return prop.type || 'any'; } -function generateMarkdown(schemaName: string, schema: any) { +function generateMarkdown(schemaName: string, schema: any, category: string, zodFile: string) { const defs = schema.definitions || {}; const mainDef = defs[schemaName] || Object.values(defs)[0]; if (!mainDef) return ''; - let md = `---\ntitle: ${schemaName}\ndescription: ${mainDef.description || schemaName + ' Schema Reference'}\n---\n\n`; + let md = ''; + // Add schema heading + md += `## ${schemaName}\n\n`; + + // Add description with better formatting if (mainDef.description) { md += `${mainDef.description}\n\n`; } if (mainDef.type === 'object' && mainDef.properties) { - md += `## Properties\n\n`; + md += `### Properties\n\n`; md += `| Property | Type | Required | Description |\n`; md += `| :--- | :--- | :--- | :--- |\n`; @@ -118,18 +122,66 @@ function generateMarkdown(schemaName: string, schema: any) { md += `| **${key}** | \`${typeStr}\` | ${isReq} | ${desc} |\n`; } + + md += `\n`; + } else if (mainDef.type === 'string' && mainDef.enum) { - md += `## Allowed Values\n\n`; + md += `### Allowed Values\n\n`; md += mainDef.enum.map((e: string) => `* \`${e}\``).join('\n'); + md += `\n\n`; } return md; } +// New function to generate combined documentation for all schemas in a zod file +function generateZodFileMarkdown(zodFile: string, schemas: Array<{name: string, content: any}>, category: string): string { + const zodTitle = zodFile.split('-').map(w => w.charAt(0).toUpperCase() + w.slice(1)).join(' '); + + let md = `---\n`; + md += `title: ${zodTitle}\n`; + md += `description: ${zodTitle} protocol schemas\n`; + md += `---\n\n`; + + md += `# ${zodTitle}\n\n`; + + // Add source reference + md += `\n`; + md += `**Source:** \`packages/spec/src/${category}/${zodFile}.zod.ts\`\n`; + md += `\n\n`; + + // Add TypeScript usage example + md += `## TypeScript Usage\n\n`; + md += `\`\`\`typescript\n`; + md += `import { `; + + // Import all schemas + const schemaNames = schemas.map(s => s.name + 'Schema').join(', '); + md += schemaNames; + md += ` } from '@objectstack/spec/${category}';\n`; + md += `import type { `; + md += schemas.map(s => s.name).join(', '); + md += ` } from '@objectstack/spec/${category}';\n\n`; + md += `// Validate data\n`; + md += `const result = ${schemas[0].name}Schema.parse(data);\n`; + md += `\`\`\`\n\n`; + + md += `---\n\n`; + + // Generate documentation for each schema + schemas.forEach((schema, idx) => { + md += generateMarkdown(schema.name, schema.content, category, zodFile); + if (idx < schemas.length - 1) { + md += `---\n\n`; + } + }); + + return md; +} + + // 2. Clean up old documentation structure -// IMPORTANT: This removes old .mdx files and subdirectories to ensure a clean state. -// Only category roots are cleaned (data/, ui/, system/, ai/, api/). The root meta.json is preserved. -// All necessary directories and files are regenerated in step 3, so this is safe. +// Remove old .mdx files and subdirectories to ensure a clean state. Object.keys(CATEGORIES).forEach(category => { const dir = path.join(DOCS_ROOT, category); if (fs.existsSync(dir)) { @@ -138,13 +190,12 @@ Object.keys(CATEGORIES).forEach(category => { const entryPath = path.join(dir, entry); const stat = fs.statSync(entryPath); - // Remove old .mdx files from category root (these will be moved to subfolders) - if (stat.isFile() && entry.endsWith('.mdx')) { + // Remove old .mdx files (will be regenerated) + if (stat.isFile() && entry.endsWith('.mdx') && entry !== 'index.mdx') { fs.unlinkSync(entryPath); console.log(`Removed old file: ${category}/${entry}`); } - // Remove old subdirectories (will be recreated with correct structure in step 3) - // Note: meta.json is preserved as it's not a directory + // Remove old subdirectories (schemas are now in single files) else if (stat.isDirectory()) { fs.rmSync(entryPath, { recursive: true, force: true }); console.log(`Removed old directory: ${category}/${entry}`); @@ -153,19 +204,19 @@ Object.keys(CATEGORIES).forEach(category => { } }); -// 3. Prepare Directories +// 3. Prepare Directories and Generate meta.json if (!fs.existsSync(DOCS_ROOT)) { fs.mkdirSync(DOCS_ROOT, { recursive: true }); } -// Generate meta.json for categories and zod file subfolders +// Generate meta.json for categories - now just listing zod files Object.entries(CATEGORIES).forEach(([key, title]) => { const dir = path.join(DOCS_ROOT, key); if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true }); const zodFiles = categoryZodFiles.get(key) || new Set(); - // Create top-level meta.json for the protocol + // Create top-level meta.json for the protocol with zod files as pages const meta: any = { title, }; @@ -174,24 +225,14 @@ Object.entries(CATEGORIES).forEach(([key, title]) => { const sortedZodFiles = Array.from(zodFiles).sort(); if (sortedZodFiles.length > 0) { - // Enforce order using 'pages' meta.pages = sortedZodFiles; } fs.writeFileSync(path.join(dir, 'meta.json'), JSON.stringify(meta, null, 2)); - - // Create zod file directories and meta.json files - sortedZodFiles.forEach(zodFile => { - const subDir = path.join(dir, zodFile); - if (!fs.existsSync(subDir)) fs.mkdirSync(subDir, { recursive: true }); - - const subTitle = zodFile.split('-').map(w => w.charAt(0).toUpperCase() + w.slice(1)).join(' '); - fs.writeFileSync(path.join(subDir, 'meta.json'), JSON.stringify({ title: subTitle }, null, 2)); - }); }); -// 4. Generate Docs -// Read JSON schema files from category subdirectories +// 4. Generate Docs - One file per zod file containing all schemas +// Group schemas by zod file Object.keys(CATEGORIES).forEach(category => { const categorySchemaDir = path.join(SCHEMA_DIR, category); @@ -202,29 +243,60 @@ Object.keys(CATEGORIES).forEach(category => { const files = fs.readdirSync(categorySchemaDir).filter(f => f.endsWith('.json')); + // Group schemas by their zod file + const zodFileSchemas = new Map>(); + files.forEach(file => { const schemaName = file.replace('.json', ''); const schemaPath = path.join(categorySchemaDir, file); const content = JSON.parse(fs.readFileSync(schemaPath, 'utf-8')); - const mdx = generateMarkdown(schemaName, content); + const zodFile = schemaZodFileMap.get(schemaName) || 'misc'; - if (mdx) { - const zodFile = schemaZodFileMap.get(schemaName); - - // Determine output directory - let outDir = path.join(DOCS_ROOT, category); - if (zodFile) { - outDir = path.join(outDir, zodFile); - } - - if (!fs.existsSync(outDir)) fs.mkdirSync(outDir, { recursive: true }); - - const fileName = `${schemaName}.mdx`; - fs.writeFileSync(path.join(outDir, fileName), mdx); - - console.log(`✓ Generated docs for ${schemaName} in ${category}${zodFile ? '/' + zodFile : ''}`); + if (!zodFileSchemas.has(zodFile)) { + zodFileSchemas.set(zodFile, []); } + zodFileSchemas.get(zodFile)!.push({ name: schemaName, content }); }); + + // Generate one file per zod file + zodFileSchemas.forEach((schemas, zodFile) => { + const outDir = path.join(DOCS_ROOT, category); + if (!fs.existsSync(outDir)) fs.mkdirSync(outDir, { recursive: true }); + + const mdx = generateZodFileMarkdown(zodFile, schemas, category); + const fileName = `${zodFile}.mdx`; + fs.writeFileSync(path.join(outDir, fileName), mdx); + + console.log(`✓ Generated docs for ${zodFile}.zod.ts in ${category} (${schemas.length} schemas)`); + }); +}); + +// 4.5. Generate Protocol Overview Pages +// Create index.mdx for each category with overview of all zod files +Object.entries(CATEGORIES).forEach(([category, title]) => { + const categoryDir = path.join(DOCS_ROOT, category); + const zodFiles = categoryZodFiles.get(category) || new Set(); + + if (zodFiles.size === 0) return; + + let overviewMd = `---\ntitle: ${title} Overview\ndescription: Complete reference for all ${title.toLowerCase()} schemas\n---\n\n`; + + overviewMd += `# ${title}\n\n`; + overviewMd += `This section contains all protocol schemas for the ${category} layer of ObjectStack.\n\n`; + + // List all zod files + const sortedZodFiles = Array.from(zodFiles).sort(); + + overviewMd += `\n`; + sortedZodFiles.forEach(zodFile => { + const zodTitle = zodFile.split('-').map(w => w.charAt(0).toUpperCase() + w.slice(1)).join(' '); + overviewMd += ` \n`; + }); + overviewMd += `\n\n`; + + // Write overview page + fs.writeFileSync(path.join(categoryDir, 'index.mdx'), overviewMd); + console.log(`✓ Generated overview page for ${category}`); }); // 5. Update Root meta.json